Export your data

Updated 2026-11-02

From the dashboard

Open Data quality and click Download every raw event. You get a file named headstream-events.ndjson, with one JSON event per line, for the selected period. You need permission to manage the project.

From the API

curl "https://headstream.app/api/v1/export?siteId=SITE_ID&from=2026-01-01&to=2026-10-31" \
  -H "Authorization: Bearer hsk_YOUR_KEY"

The response has rows and nextCursor. Each page holds up to 5,000 events. Pass nextCursor back as cursor, and stop when it's null:

curl "https://headstream.app/api/v1/export?siteId=SITE_ID&from=2026-01-01&to=2026-10-31&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer hsk_YOUR_KEY"

Keep the same from and to for every page. Without them, the range is the last 30 days. A bad cursor returns 400 with the code invalid_cursor, so start again without one.

With the 120 requests per minute limit, one key can read up to about 600,000 events a minute.

From MCP

export_events takes siteId, days, cursor and limit. limit defaults to 500 and goes up to 5,000.

What's included

The export holds every raw event, including bots. Reports leave bots out, so raw totals will be higher. Filter on is_bot to compare them. Rows also include events your exclusion rules flagged, since those are flagged and not deleted.

Each row has event_id, type, name, ts, received_at, anonymous_id, session_id, host, path, url, referrer, referrer_host, utm_source, utm_medium, utm_campaign, utm_term, utm_content, click_id_type, click_id, ip, user_agent, country, region, city, device, browser, is_bot and properties.

Secrets in URLs are removed before storage, such as password and token query parameters, and card numbers are redacted.

Revenue rows

The event export covers site events. For revenue, use GET /api/v1/explain?siteId=SITE_ID&metric=revenue&limit=1000. It returns ledger rows, up to 1,000, each with an entry_id. Use GET /api/v1/explain/payment with entryId to trace one entry to every credited visit. See the API docs. Revenue needs Stripe, and connecting Stripe is in beta.

Metrics behind reports

To see the rows behind a number instead of everything, use GET /api/v1/explain, or open the number's Why this number page. See trust.