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:

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

# 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 because ad blockers can block tracking scripts.

Set a default website

To avoid typing --website on every command:

datafast config set-website <websiteId>

Overview

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

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:

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:

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:

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

Output tips

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

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

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown