Export API 
With this API you can export raw data points (without sampling). Data points are page views and events. Use the type parameter to export page views (the default), events, or both. Define a date range and it pulls out the data. The response will only include the selected fields.
We now call the short-lived value formerly known as a session ID a page-load ID. The export field is still named
session_id. It groups data only within one actual page load; it is not stored on the visitor’s device and does not continue across reloads or full navigations.
Want to use a simple interface to export your data? See our video on exporting data.
When using the API, it’s recommended to generate the export URL via the export your data interface. It has a simple UI where fields can be selected without any coding or technical knowledge.
Available fields in export
| Field | Type | Description |
|---|---|---|
| added_unix | number | The time of the page view in UNIX time format |
| added_iso | date | The time of the page view in ISO8601 format |
| added_date | date | The date of the data point in YYYY-MM-DD format (UTC) |
| hostname | string | The hostname of the website |
| hostname_original | string | When the hostname is overwritten, we store the original hostname |
| path | string | The path of the page view |
| query | string | The query parameters of the URL |
| path_and_query | string | The path followed by the query parameters |
| is_unique | boolean | Is this page view unique |
| is_robot | boolean | Is page view visited by a robot or crawler |
| document_referrer | string | The JavaScript document.referrer of the page |
| referrer_hostname | string | The hostname of the referrer (normalized) |
| referrer_path | string | The path of the referrer |
| utm_source | string | UTM source (specify via ref= or utm_source in your URL) |
| utm_medium | string | UTM medium (specify via utm_medium in your URL) |
| utm_campaign | string | UTM campaign (specify via utm_campaign in your URL) |
| utm_content | string | UTM content (specify via utm_content in your URL) |
| utm_term | string | UTM term (specify via utm_term in your URL) |
| scrolled_percentage | number | How far did a visitor scroll on the page (in steps of 5%) |
| duration_seconds | number | How many seconds did a visitor stay on this page (we stop the counter when a page is hidden) |
| viewport_width | number | Viewport width in pixels |
| viewport_height | number | Viewport height in pixels |
| screen_width | number | Screen width in pixels |
| screen_height | number | Screen height in pixels |
| user_agent | string | The navigator.userAgent of a browser (in case of a fake one we don’t store it. |
| device_type | string | Either desktop, mobile, tablet, or tv. |
| country_code | string | 2 letter country code |
| browser_name | string | Browser name |
| browser_version | string | Browser version (do note this is a string) |
| os_name | string | OS name |
| os_version | string | OS version (do note this is a string) |
| lang_region | string | The region part of navigator.language |
| lang_language | string | The language part of navigator.language |
| uuid | string | A UUID v4 of the page view (this is not always unique) |
| datapoint | string | The event name, or pageview for page views (only with type=events or type=all) |
| session_id | string | Legacy field name for the page-load ID; retained for backward compatibility |
| metadata.*** | N/A | Metadata are your own specified fields followed by a type (e.g. project_text) |
Data like scrolled_percentage and duration_seconds is not always added because it depends on the browser features of the visitor. Metadata is found in metadata.*** fields. They will only be exported when specified by key (e.g.: metadata.dark_mode_bool).
Deprecated fields
These fields are deprecated but we keep them for backward compatibility. It’s recommended to not use it for new projects. You can only select them in fields when you leave out the version parameter. If you leave out fields, page view exports return them by default.
| Field | Description |
|---|---|
| url | Please use hostname and path to get the full URL |
| referrer | We replaced this with document_referrer |
| referrer_raw | We replaced this with document_referrer |
| device_width_pixels | We replaced this with viewport_width |
| device_width | We replaced this with viewport_width |
| source | What is the source of this page view, mostly js from our JavaScript |
Authenticate
For this API you’ll need to authenticate, unless your website is public. See the authenticate page on how to authenticate.
When a public website hides its top pages, fields that contain page paths (path, query, path_and_query, url, document_referrer, referrer_path, and the deprecated referrer and referrer_raw) need an API key with access to the website. Without a key, these requests return HTTP 403.
In short: apply an Api-Key-header where the key starts with sa_api_key_.... The User-Id header in the examples is optional for this API.
Query parameters
| Parameter | Description |
|---|---|
hostname |
The website to export (required) |
start |
The start date as YYYY-MM-DD, YYYY-MM-DDTHH (hourly), or a date placeholder (defaults to 30 days ago) |
end |
The end date in the same format (defaults to today) |
timezone |
The time zone of the dates, like Europe/Amsterdam (defaults to UTC) |
fields |
A comma separated list of fields to export. Always specify it: without it, you get a legacy set of fields, and type=all returns an error |
type |
pageviews (default), events, or all for page views and events |
format |
csv (default), csv-excel, tsv, json, ndjson, parquet, or avro (see formats) |
robots |
Set to true to include data points from robots (defaults to false) |
version |
The version of the API (the latest version is 6). Without a version, the deprecated fields are available |
Formats
csvandtsv: comma or tab separated values with a header row.csv-excel: CSV with asep=,first line, so Microsoft Excel detects the separator.json: one JSON object with adatapointsarray and ametaobject.ndjson: one JSON object per line.parquetandavro: typed binary formats for data tools. Column names are converted to camel case and dots become underscores, with exceptions for_id,utm_,os_, anduuid. For example,added_isobecomesaddedIso,session_idbecomessessionID,utm_sourcebecomesuTMsource, andmetadata.app_id_textbecomesmetadata_appIDText. Number metadata (_int) is exported as a double and date metadata (_date) as text.
Selecting fields
You can specify all fields you like to export. Add them as a comma separated list (e.g.: &fields=added_iso,hostname,path).
Request example (for developers)
To test if your API key works correctly you can replace the example values of this cURL example with your own.
# Export daily data
curl "https://simpleanalytics.com/api/export/datapoints?version=6&format=csv&hostname=simpleanalytics.com&start=2026-09-20&end=2026-10-20&robots=false&timezone=Europe%2FAmsterdam&fields=added_iso,path&type=pageviews" \
-H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000' \
-H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: text/csv'
# Export hourly data (for 3PM today in Amsterdam)
curl "https://simpleanalytics.com/api/export/datapoints?version=6&format=csv&hostname=simpleanalytics.com&start=2026-10-20T15&end=2026-10-20T15&robots=false&timezone=Europe%2FAmsterdam&fields=added_iso,path&type=pageviews" \
-H 'User-Id: sa_user_id_00000000-0000-0000-0000-000000000000' \
-H 'Api-Key: sa_api_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-H 'Content-Type: text/csv'
If you choose to export in the CSV format, it will export something like this:
| added_iso | country_code | datapoint | device_type | path | session_id | utm_campaign | utm_content | utm_medium | utm_source |
|---|---|---|---|---|---|---|---|---|---|
| 2026-10-19T14:05:07.100Z | US | visit_homepage | desktop | / | 1e5aad53-c734-40ac-b060-426a70d1c104 | ads1 | duckduckgo | ||
| 2026-10-20T12:30:52.100Z | UK | visit_homepage | desktop | / | 7b03aa29-612d-4aa8-b147-72c13986c4ae | newsletter | |||
| 2026-10-20T12:34:52.200Z | UK | popup_show | desktop | / | 7b03aa29-612d-4aa8-b147-72c13986c4ae | ||||
| 2026-10-20T13:12:57.100Z | NL | visit_homepage | desktop | / | 928e4f2f-1f16-4900-9ad8-0a1965e689a3 | ||||
| 2026-10-20T13:13:17.200Z | NL | popup_show | desktop | / | 928e4f2f-1f16-4900-9ad8-0a1965e689a3 | ||||
| 2026-10-20T13:13:47.300Z | NL | popup_close | desktop | / | 928e4f2f-1f16-4900-9ad8-0a1965e689a3 |
The above export in CSV format
added_iso,country_code,datapoint,device_type,path,session_id,utm_campaign,utm_content,utm_medium,utm_source
2026-10-19T14:05:07.100Z,US,visit_homepage,desktop,/,1e5aad53-c734-40ac-b060-426a70d1c104,ads1,,,duckduckgo
2026-10-20T12:30:52.100Z,UK,visit_homepage,desktop,/,7b03aa29-612d-4aa8-b147-72c13986c4ae,,,newsletter,
2026-10-20T12:34:52.200Z,UK,popup_show,desktop,/,7b03aa29-612d-4aa8-b147-72c13986c4ae,,,,
2026-10-20T13:12:57.100Z,NL,visit_homepage,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,google
2026-10-20T13:13:17.200Z,NL,popup_show,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,
2026-10-20T13:13:47.300Z,NL,popup_close,desktop,/,928e4f2f-1f16-4900-9ad8-0a1965e689a3,,,,
Metadata fields
Because metadata fields are defined by the user, we don’t know the fields upfront. The export UI gives a good overview of all metadata fields available for a certain period. Use those fields in the export API.
Fields in the API and exporter have a type appended to them. You can see fields like metadata.fieldname_text, metadata.fieldname_date, metadata.fieldname_bool, or metadata.fieldname_int (where fieldname is a user-defined name). Some metadata fields can have both, for example, metadata.projectID_text and metadata.projectID_int. If a text looks like a number, we convert it to an integer and we keep the text version.
When you see something prefixed with metadata.sa_urlparam_, it’s a parameter from the allowed URL parameters feature.
Event counts
If you are only interested in how many certain events happened, you can use our Stats API. It has a simple request and response with event totals.
https://simpleanalytics.com/simpleanalytics.com.json?version=6&start=yesterday&end=today&timezone=Europe/Amsterdam&events=visit_pricing
See live example of output.
Hourly data export
You can now export data for specific hours of a day. This allows for more granular data analysis when you need to understand traffic patterns within a single day.
To export hourly data, append the hour to your date in the format YYYY-MM-DDTHH where HH is the hour in 24-hour format (00-23).
Important constraints for hourly exports:
- Both
startandendparameters must include the hour - The start and end dates must be the same (you can only export hourly data for a single day at a time)
- Hours must be between 00 and 23
- The hours are in the timezone you specify in the
timezoneparameter
Example:
# Export data for 2PM on July 4th, 2025
curl "https://simpleanalytics.com/api/export/datapoints?version=6&format=csv&hostname=example.com&start=2025-07-04T14&end=2025-07-04T14&fields=added_iso,path" \
-H 'User-Id: sa_user_id_...' \
-H 'Api-Key: sa_api_key_...'
Errors
When a request fails, the response is JSON with "ok": false and an error message. If a website on the Free plan is locked because its Simple Analytics badge is missing, the API returns HTTP 423 with "code": "BADGE_REQUIRED".
Performance
For us it does not matter how much data you export. We stream the data directly out of our database to your server or computer. No heavy load required.
To make the export size smaller only select the fields you need.
If you have any problems, drop us a line via our contact page.