Source: https://datafa.st/docs/cli-analytics
Markdown source: https://datafa.st/docs/cli-analytics.md
Description: Query your website analytics — overview, time series, breakdowns, and realtime — using the DataFast CLI.

# CLI — Analytics

Query your analytics data from the terminal. Works with both `dft_` admin tokens and `df_` site keys.

Run `datafast analytics` to choose and run a report interactively. When using a `dft_` account token, analytics subcommands prompt you to choose a website if you do not pass `--website` or configure a default website. A `df_` website API key is already scoped to one website, so no website prompt is needed.

## Common flags

All analytics commands accept these flags:

| Flag | Description |
|---|---|
| `--website <id>` | Website ID — required with `dft_` tokens; skip when using a `df_` site key |
| `--website-id <id>` | Alias for `--website` |
| `--period <period>` | Dashboard preset: `today`, `yesterday`, `last24h`, `last7d`, `last30d`, `last12m`, `week`, `month`, `year`, `all` |
| `--from <date>` | Custom range start as `YYYY-MM-DD`, or an exact ISO timestamp with `Z`/offset |
| `--to <date>` | Custom range end as `YYYY-MM-DD`, or an exact ISO timestamp with `Z`/offset |
| `--fields <fields>` | Comma-separated fields to include in the response |
| `--limit <n>` | Max results (default: 50) |
| `--offset <n>` | Pagination offset (default: 0) |
| `--timezone <tz>` | Optional IANA timezone override, e.g. `America/New_York` |

## Date and timezone rules

- Prefer `--period` for dashboard presets. The CLI resolves these like the dashboard in the website timezone.
- Use `--from YYYY-MM-DD --to YYYY-MM-DD` for custom calendar ranges. Date-only values are interpreted by the API in the website timezone unless `--timezone` is provided.
- Do not use bare datetimes like `2024-01-01T00:00:00`; they are ambiguous and rejected. Exact instants must include `Z` or an offset, like `2024-01-01T00:00:00Z` or `2024-01-01T00:00:00-08:00`.

## Revenue fields

- `overview` and `timeseries` revenue is total business revenue from payments.
- Breakdown commands such as `pages`, `referrers`, `countries`, `browsers`, and `os` return attributed revenue for revenue attribution.
> Breakdown revenue is attribution data: it shows which pages, sources, countries, and devices influenced new revenue. For up to 30% better attribution accuracy, set up [proxy tracking](/docs/proxy-guide) because ad blockers can block tracking scripts.

## Set a default website

To avoid typing `--website` on every command:

```sh
datafast config set-website <websiteId>
```

## Overview

Get a summary of visitors, sessions, revenue, and more:

```sh
datafast analytics overview
datafast analytics overview --website <id>
datafast analytics overview --website <id> --period today
datafast analytics overview --website <id> --period last30d
datafast analytics overview --website <id> --from 2024-01-01 --to 2024-01-31
datafast analytics overview --website <id> --fields visitors,revenue
```

## Time series

Get data over time. By default, this returns visitors, sessions, revenue, and conversion rate by day:

```sh
datafast analytics timeseries
datafast analytics timeseries --website <id>
datafast analytics timeseries --website <id> --period last24h
datafast analytics timeseries --website <id> --fields visitors,sessions --interval day
datafast analytics timeseries --website-id <id> --fields visitors,revenue --interval month --from 2024-01-01 --to 2024-12-31
```

**Fields:** `name`, `visitors`, `sessions`, `revenue`, `conversion_rate`

**Intervals:** `hour`, `day`, `week`, `month`

## Breakdowns

Each command returns a ranked list for that dimension. The `revenue` field here means attributed revenue for revenue attribution, not total business revenue:

```sh
datafast analytics pages
datafast analytics pages      --website <id>   # Top pages
datafast analytics referrers  --website <id>   # Traffic sources
datafast analytics countries  --website <id>   # Countries
datafast analytics regions    --website <id>   # Regions
datafast analytics cities     --website <id>   # Cities
datafast analytics browsers   --website <id>   # Browsers
datafast analytics devices    --website <id>   # Devices
datafast analytics os         --website <id>   # Operating systems
datafast analytics campaigns  --website <id>   # UTM campaigns
datafast analytics goals      --website <id>   # Custom goals / events
datafast analytics hostnames  --website <id>   # Hostnames
datafast analytics metadata   --website <id>   # Custom metadata
```

All breakdown commands accept the common flags above.

## Realtime

Get the current live visitor count:

```sh
datafast analytics realtime
datafast analytics realtime --website <id>
```

## Output tips

```sh
# Compact JSON — pipe into jq
datafast --json analytics overview --website <id> | jq '.visitors'

# Save to file
datafast --json analytics pages --website <id> > pages.json
```