This feature is available on the Enterprise plan only or as an add-on to the Growth plan. If interested in adding this feature please contact support@userpilot.co.
The Userpilot Export Analytics Data API allows you to export analytics data from Userpilot, enabling you to analyze user behavior, engagement, and more. You can filter the data by date range, user, company, event type, and additional parameters. The API supports exporting data in JSON or CSV formats.

​
Authorization

Userpilot API uses an API key to authenticate requests. You can find your API key on the Environment Page. Authentication Method: Include your API key in the Authorization header: 
Authorization: Token {{API_KEY}}
All API requests must be made over HTTPS.
Your API key carries many privileges, so be sure to keep it secure! Do not share your secret API keys in publicly accessible areas.

​
Rate Limits

The export API is limited to one export job per application token at a time. If you attempt to create another export job while one is already in progress, the API will return a 409 Conflict error.

​
Data Restrictions

  • Job Status Availability: Once an export job is created, the job status and related information will be available for 3 days. After this period, the job status will no longer be accessible via the API.
  • File Download Expiry: The URLs generated to download the exported data files will expire after 2 days. Ensure you download the files within this time frame, as the links will no longer be valid afterward.
Providing a valid email address in the request is recommended. You’ll receive a notification with download links when the export is ready, eliminating the need to manually check job status.
For the schema of exported events and data, see the Event Schema page.
For details on available lookup endpoints and how to use them, see the Data Lookups page.

​
Data Schema Reference

The data exported via the Userpilot Export Analytics Data API follows the Userpilot Event Data Schema. This schema defines the structure, attributes, and relationships of all events, users, and companies included in your export. Key points:
  • Each exported event will include fields such as app_token, event_type, event_name, user_id, company_id, source, inserted_at, and more.
  • Auto-captured attributes (e.g., hostname, device_type, browser, etc.) and custom attributes (in the metadata object) are included as described in the schema.
  • The schema covers all event types (identify_user, identify_company, track, track_feature, page_view, interaction, etc.) and their specific attribute structures.
Your exported data may include new or additional fields as the schema evolves. Please ensure your data processing pipelines can handle unexpected fields gracefully.

​
API Endpoints

​
1. Trigger an Export Job

​
Endpoint

POST https://appex.userpilot.io/api/v1/analytics/exports

​
Description

Creates an export job to extract analytics data based on the specified parameters.

​
Parameters

ParameterTypeRequiredDescriptionExample
fromstringYesStart date of the export in YYYY-MM-DD format.”2024-05-02”
tostringYesEnd date of the export in YYYY-MM-DD format.”2024-09-30”
emailsstring[]NoList of email addresses to receive the exported data. If omitted, no email is sent.[“example@work.com”]
event_typestring[]NoList of event types to filter. Defaults: see below.[“track”, “page_view”]
user_idstring[]NoSpecific user IDs to filter. If omitted, all users are included.[“123456”]
company_idstring[]NoSpecific company IDs to filter. If omitted, all companies are included.[“13162551529”]
segment_idstringNoFilter data based on a specific segment.”987654”
formatstringNoFormat of the exported data. Options: json (default) or csv.”csv”
exclusionsbooleanNoExclude users/companies set in the web app. Default: false.true
Default values:
  • event_type defaults to ["identify_user", "identify_company", "page_view", "track", "track_feature", "interaction"] if not provided.
  • user_id and company_id default to empty arrays ([]), meaning all users or companies are included by default.
  • The default export format is json.

​
Example Request

curl --location 'https://appex.userpilot.io/api/v1/analytics/exports' \
--header 'Authorization: Token {{API_KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from": "2024-05-02",
    "to": "2024-09-30",
    "emails": ["example@work.com"],
    "event_type": ["identify_user", "identify_company", "page_view", "track"],
    "user_id": ["user_1"],
    "company_id": ["comp_2"],
    "segment_id": "9",
    "format": "csv",
    "exclusions": true
}'

{
  "environment_app_token": "NX-51f4acf7",
  "environment_name": "production",
  "job_id": "86f4dd75-00c8-40cd-ac6a-3dce8440be0c",
  "links": "/api/v1/analytics/exports/jobs/86f4dd75-00c8-40cd-ac6a-3dce8440be0c",
  "start_time": "2024-10-06T10:44:50.999504"
}

​
2. Show Jobs

​
Endpoint

GET https://appex.userpilot.io/api/v1/analytics/exports/jobs

​
Description

Retrieves a list of all export jobs triggered by your API token.

​
Example Request

curl --location 'https://appex.userpilot.io/api/v1/analytics/exports/jobs' \
--header 'Authorization: Token {{API_KEY}}'

[
  {
    "elapsed_time": "44 seconds",
    "elapsed_time_seconds": 44,
    "end_time": "2024-09-22T11:20:58.006463Z",
    "job_id": "af257e48-c145-40aa-996c-dad64839acb1",
    "progress": "5 out of 5 partitions",
    "start_time": "2024-09-22T11:20:14.731634",
    "status": "completed"
  }
]

​
3. Show Job by Job ID

​
Endpoint

GET https://appex.userpilot.io/api/v1/analytics/exports/jobs/{job_id}

​
Description

Retrieves detailed information about a specific export job identified by its job_id.

​
Path Parameters

ParameterTypeRequiredDescription
job_idStringYesThe unique identifier of the export job

​
Example Request

curl --location 'https://appex.userpilot.io/api/v1/analytics/exports/jobs/{job_id}' \
--header 'Authorization: Token {{API_KEY}}'

{
  "app_token": "<YOUR-APP-TOKEN>",
  "completed_chunks": ["2024-05-01", "2024-06-01"],
  "current_chunk": "2024-09-01",
  "end_time": "2024-09-22T13:18:11.558646Z",
  "job_id": "664314e1-ee60-48eb-a36a-5f38f4c524f1",
  "presigned_urls": [
    {"filename": "2024-07-29.json.gz", "url": "https://..."}
  ],
  "progress": "2 out of 5 partitions",
  "start_time": "2024-09-22T13:17:26.864860Z",
  "status": "completed",
  "all_chunks": ["2024-05-01", "2024-06-01"],
  "type": "export"
}
  • Ensure you retrieve job details within the 3-day availability window to effectively monitor ongoing jobs.
  • Download links for exported data will expire after 2 days, so make sure to download your data promptly.

​
Contact Support

If you have any questions or need further assistance, please contact our support team at support@userpilot.co.