Reports and dashboards

Updated 2026-11-02

Reports

Open Reports in the dashboard, or run any report with one request:

curl -X POST https://headstream.app/api/v1/reports/run \
  -H "Authorization: Bearer hsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"SITE_ID","spec":{"kind":"breakdown","dimension":"utm_campaign","days":30}}'

A spec has a kind. days is 1 to 365 and defaults to 30.

`kind`	Other fields	Shows
`summary`	`filters`	Visitors, pageviews, sessions, bounce rate
`trend`	`metric`, `filters`	Visitors or pageviews per day
`breakdown`	`dimension`, `limit`, `filters`	Top values for a dimension
`revenue_trend`	`model`	Revenue per day
`revenue_breakdown`	`dimension`, `model`	Revenue by `channel`, `campaign`, `source` or `landing_path`
`revenue_change`	`model`	Waterfall of what moved revenue, by channel
`flow`	`metric`, `model`	Sankey flows
`funnel`	`steps`	Drop-off across steps
`map`	`filters`	Visitors by country
`goals`		Goals and conversion rates
`self_reported`		Self-reported answers against tracking

model is first_touch, last_touch, linear or u_shaped, and defaults to linear.

Revenue reports need Stripe, which is in beta. Amounts are in minor currency units, so 1250 means $12.50.

Dimensions and filters

Dimensions are path, referrer_host, utm_source, utm_campaign, country, city, device and browser. For breakdown, limit is 1 to 25.

filters narrows a report. For example, { "country": "US" }.

Funnels

{ "kind": "funnel", "days": 30, "steps": ["/pricing", "/signup", "signup"] }

A funnel has 2 to 6 steps. A step is an exact path, a path ending in *, or a custom event name. A visitor counts when they complete the steps in order within seven days. Each step returns visitors, shareOfFirst and shareOfPrevious.

Flows

flow with metric set to sessions shows channel, then landing page, then next step. With metric set to revenue, it shows channel, then landing page, then revenue.

Dashboards

A dashboard holds saved reports, and each one reruns on live data when opened. Create one:

curl -X POST https://headstream.app/api/v1/dashboards \
  -H "Authorization: Bearer hsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"SITE_ID","name":"Weekly"}'

Then add a report, with {id} set to the new dashboard's ID:

curl -X POST https://headstream.app/api/v1/dashboards/{id}/reports \
  -H "Authorization: Bearer hsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId":"SITE_ID","title":"Top campaigns","spec":{"kind":"breakdown","dimension":"utm_campaign"}}'

The AI assistant

The sidebar assistant, built on Claude, answers from live reports and can build dashboards for you.

Check a number

Every core metric has a Why this number page, with the definition and raw rows. See the API docs and trust.