Skip to main content
The Export API allows you to download raw event data for backup, analysis, or integration with other tools.

​
Export events

GET /api/websites/:id/export Export raw events for a website in CSV or JSON format.

​
Path parameters

​
id
string
required
Website ID (format: site_XXXXXXXXXX)

​
Query parameters

​
start_date
string
required
Start date (YYYY-MM-DD)
​
end_date
string
required
End date (YYYY-MM-DD)
​
format
string
Export format: csv or json. Defaults to csv.
​
timezone
string
Timezone for timestamps. Defaults to UTC.
​
event_type
string
Filter by event type: pageview, event, or omit for all events
​
include_bots
boolean
Include bot traffic. Defaults to false.
Maximum date range: 90 days per export

​
Response

Returns a file download with appropriate Content-Type header:
  • CSV: text/csv; charset=utf-8
  • JSON: application/json

​
CSV format

timestamp,event_type,url,event_name,event_data,visitor_id,session_id,country,region,city,browser,os,device,referrer,utm_source,utm_medium,utm_campaign
2026-03-03T10:15:00Z,pageview,/,,,a1b2c3d4e5f6g7h8,sess_xyz789,US,CA,San Francisco,Chrome,macOS,desktop,https://google.com,,,
2026-03-03T10:16:30Z,event,,signup_click,"{""plan"":""pro""}",a1b2c3d4e5f6g7h8,sess_xyz789,US,CA,San Francisco,Chrome,macOS,desktop,,,,

​
JSON format

[
  {
    "timestamp": "2026-03-03T10:15:00Z",
    "event_type": "pageview",
    "url": "/",
    "event_name": null,
    "event_data": null,
    "visitor_id": "a1b2c3d4e5f6g7h8",
    "session_id": "sess_xyz789",
    "country": "US",
    "region": "CA",
    "city": "San Francisco",
    "browser": "Chrome",
    "os": "macOS",
    "device": "desktop",
    "referrer": "https://google.com",
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null
  },
  {
    "timestamp": "2026-03-03T10:16:30Z",
    "event_type": "event",
    "url": null,
    "event_name": "signup_click",
    "event_data": {"plan": "pro"},
    "visitor_id": "a1b2c3d4e5f6g7h8",
    "session_id": "sess_xyz789",
    "country": "US",
    "region": "CA",
    "city": "San Francisco",
    "browser": "Chrome",
    "os": "macOS",
    "device": "desktop",
    "referrer": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null
  }
]

​
Example

curl -X GET "https://analytics.example.com/api/websites/site_abc123/export?start_date=2026-03-01&end_date=2026-03-07&format=csv" \
  -H "Authorization: Bearer spk_selfhosted_abc123..." \
  -o events.csv

​
Export limits

Large exports can be memory-intensive. Consider these limits:
  • Maximum 90 days per export
  • Exports with >1M events may take several minutes
  • No pagination - entire date range is exported in one file
  • No rate limiting, but exports are resource-intensive
For websites with high traffic, export data in smaller chunks: 
# Export one week at a time
for week in {1..12}; do
  start_date=$(date -d "2026-01-01 + $((week-1)) weeks" +%Y-%m-%d)
  end_date=$(date -d "2026-01-01 + $week weeks" +%Y-%m-%d)
  
  curl -X GET "https://analytics.example.com/api/websites/site_abc123/export?start_date=$start_date&end_date=$end_date&format=csv" \
    -H "Authorization: Bearer spk_selfhosted_abc123..." \
    -o "events_week_$week.csv"
  
  sleep 5  # Rate limit yourself
done

​
Privacy considerations

Exported data includes visitor IDs, which are privacy-preserving hashes that rotate daily. Visitor IDs cannot be used to identify individual users across days.

​
GDPR compliance

When exporting data:
  • Visitor IDs are anonymized hashes, not actual user identifiers
  • No personally identifiable information (PII) is stored or exported
  • IP addresses are never stored or exported
  • Consider your data retention obligations when exporting and storing data

​
Use cases

Backup & Archive

Export historical data for long-term backup and archival

Custom Analysis

Import into Excel, Tableau, or other analytics tools for custom analysis

Data Warehouse Integration

Load event data into your data warehouse for cross-platform analysis

Machine Learning

Use exported data for training ML models on user behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us