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 enforces rate limiting to ensure reliable data export operations and maintain system performance for all users. These limits help balance resource usage while enabling comprehensive analytics data retrieval.

​
Rate Limit Details

  • Job Limitation: One export job at a time per application token

​
Error Responses

The API returns specific error codes when limits are exceeded:
  • 409 Conflict: Returned when attempting to create a new export job while another is in progress

​
Best Practices

Verify Job Status: Always check for existing export jobs before initiating a new one to avoid conflicts.Handle Conflicts Gracefully: When encountering a 409 Conflict error, wait for the current job to complete before retrying.Track Export Progress: Use job status endpoints to monitor export completion and download files promptly.Optimize Export Requests: Use specific date ranges and filters to reduce data volume and improve performance.

​
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
The endpoint URL uses the appex environment. For EU data residency, use appex-eu instead. See Environment Settings for your specific endpoint.

​
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.