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` |
| `-F, --filter <filter>` | Dashboard-style analytics filter. Repeat to combine filters. |

## 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`.

## Filters

The CLI uses the same filter system as the dashboard. This lets you answer questions like "show analytics for visitors from the United States on iOS", then run another command on the same segment to drill down by page, source, country, browser, or revenue over time.

Generic syntax:

```sh
datafast analytics <report> --filter <key>=<value>
datafast analytics <report> --filter <key>:<operator>=<value>
datafast analytics <report> --filter <key>=<operator>:<value>
```

`--filter` can be repeated and also has the short alias `-F`.

### Operators

| Operator | Meaning |
|---|---|
| `is` | Include matching values. This is the default. |
| `is_not` | Exclude matching values. |
| `contains` | Partial match. Only supported for `page` and `entry_page`. |
| `does_not_contain` | Negative partial match. Only supported for `page` and `entry_page`. |

### Filter keys

| Group | Keys |
|---|---|
| URL | `hostname`, `page`, `entry_page` |
| Source | `referrer`, `ref`, `source`, `via` |
| UTM | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
| Location | `country`, `region`, `city` |
| System | `browser`, `os`, `device` |
| Custom | `goal` |

Friendly aliases are available for the same keys: `--country`, `--region`, `--city`, `--browser`, `--os`, `--device`, `--referrer`, `--page`, `--entry-page`, `--hostname`, `--goal`, `--utm-source`, `--utm-medium`, `--utm-campaign`, `--utm-term`, `--utm-content`, `--ref`, `--source`, and `--via`.

### Filter examples

```sh
# Country is United States + OS is iOS
datafast analytics overview --website <id> --country "United States" --os iOS

# Rank docs pages only
datafast analytics pages --website <id> --filter page:contains=/docs --limit 25

# Mobile visitors from the United States, grouped by referrer
datafast analytics referrers --website <id> --country "United States" --device mobile

# Revenue time series excluding docs traffic
datafast analytics timeseries --website <id> --fields visitors,revenue --interval day \
  --filter page:does_not_contain=/docs

# Paid campaign traffic from selected countries
datafast analytics campaigns --website <id> \
  -F utm_source=google,facebook \
  -F country="United States,Canada"

# Visitors who completed a payment goal, grouped by country
datafast analytics countries --website <id> --goal payment --period last30d
```

Notes:

- Multiple values in one filter are comma-separated, e.g. `--filter country="United States,Canada"`.
- Repeating the same key with the same operator merges the values.
- Do not mix different operators for the same key in one command.
- Filters work on `overview`, `timeseries`, and analytics breakdown commands. `realtime` and `metadata` are not segmentable reports.

## 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
datafast analytics overview --website <id> --country "United States" --os iOS
```

## 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
datafast analytics timeseries --website <id> --fields visitors,revenue --interval day --filter page:contains=/docs
```

**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 pages      --website <id> --filter page:contains=/docs
datafast analytics referrers  --website <id>   # Traffic sources
datafast analytics referrers  --website <id> --country "United States" --device mobile
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
```