Bulk Data Export API

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 [email protected].

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, session_start, 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

Parameter	Type	Required	Description	Example
`from`	`string`	Yes	Start date of the export in `YYYY-MM-DD` format.	”2024-05-02”
`to`	`string`	Yes	End date of the export in `YYYY-MM-DD` format.	”2024-09-30”
`emails`	`string[]`	No	List of email addresses to receive the exported data. If omitted, no email is sent.	[“[email protected]”]
`event_type`	`string[]`	No	List of event types to filter. Defaults: see below.	[“track”, “page_view”]
`user_id`	`string[]`	No	Specific user IDs to filter. If omitted, all users are included.	[“123456”]
`company_id`	`string[]`	No	Specific company IDs to filter. If omitted, all companies are included.	[“13162551529”]
`segment_id`	`string`	No	Filter data based on a specific segment.	”987654”
`format`	`string`	No	Format of the exported data. Options: `json` (default) or `csv`.	”csv”
`exclusions`	`boolean`	No	Exclude 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", "session_start"] 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": ["[email protected]"],
    "event_type": ["identify_user", "identify_company", "page_view", "track"],
    "user_id": ["user_1"],
    "company_id": ["comp_2"],
    "segment_id": "9",
    "format": "csv",
    "exclusions": true
}'

Success
409 Conflict
401 Unauthorized

{
  "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"
}

{
    "errors": [
        {
            "details": "There is already an export job in progress, you can only have one export job in progress at a time.",
            "error": "Conflict",
            "error_code": "409",
            "message": "The request could not be completed due to a conflict with the current state of the target resource."
        }
    ]
}

{
    "errors": [
        {
            "details": "Your current plan for application NX-d7ce194a does not support the feature you are trying to access.",
            "error": "Unauthorized",
            "error_code": "401",
            "message": "You are not authorized to perform the requested action."
        }
    ]
}

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}}'

Success

[
  {
    "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

Parameter	Type	Required	Description
job_id	String	Yes	The 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}}'

Success
404 Not Found

{
  "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"
}

{
    "errors": [
        {
            "details": null,
            "error": "Resource not found",
            "error_code": "404",
            "message": "Failed to retrieve job with id ...: job not found"
        }
    ]
}

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.

Understanding File Names and Date Ranges

The Export API partitions data into files by weeks to avoid oversized files. It’s important to understand how file names relate to the data they contain.

File Naming Convention

Weekly Partitioning: Each file represents a weekly partition of data
File Name Format: Each weekly file’s name is the date representing the start of the week (Monday) in YYYY-MM-DD format
Data Filtering: The file name does not indicate that the file contains all data from that entire week. The data within each file is still restricted to your requested date range filter

Example Scenario

If you request data for the date range November 30, 2025 → December 2, 2025, you may receive files with names that appear outside this range:

File: 2025-11-24.json.gz
- November 30, 2025 belongs to the week starting November 24, 2025 (Monday)
- This file contains data for November 30, 2025 only (matching your filter)
- The file name reflects the week start date, not the actual data range
File: 2025-12-01.json.gz
- December 2, 2025 belongs to the week starting December 1, 2025 (Monday)
- This file contains data for December 1, 2025 and December 2, 2025 (matching your filter)
- Again, the file name reflects the week start date

Key Points

File names represent the week start date (Monday) for organizational purposes
The actual data in each file is filtered to your requested date range
You may see file names with dates outside your requested range, but the data inside will only include events within your specified from and to dates
This partitioning approach helps manage file sizes while maintaining efficient data retrieval

Contact Support

If you have any questions or need further assistance, please contact our support team at [email protected].

APIs

Real-time HTTP

Bulk Identify/Update

Bulk Import

Bulk Export

Bulk Delete

Authorization

Rate Limits

Rate Limit Details

Error Responses

Best Practices

Data Restrictions

Data Schema Reference

API Endpoints

1. Trigger an Export Job

Endpoint

Description

Parameters

Example Request

2. Show Jobs

Endpoint

Description

Example Request

3. Show Job by Job ID

Endpoint

Description

Path Parameters

Example Request

Understanding File Names and Date Ranges

File Naming Convention

Example Scenario

Key Points

Contact Support

APIs

Real-time HTTP

Bulk Identify/Update

Bulk Import

Bulk Export

Bulk Delete

​Authorization

​Rate Limits

​Rate Limit Details

​Error Responses

​Best Practices

​Data Restrictions

​Data Schema Reference

​API Endpoints

​1. Trigger an Export Job

​Endpoint

​Description

​Parameters

​Example Request

​2. Show Jobs

​Endpoint

​Description

​Example Request

​3. Show Job by Job ID

​Endpoint

​Description

​Path Parameters

​Example Request

​Understanding File Names and Date Ranges

​File Naming Convention

​Example Scenario

​Key Points

​Contact Support

Authorization

Rate Limits

Rate Limit Details

Error Responses

Best Practices

Data Restrictions

Data Schema Reference

API Endpoints

1. Trigger an Export Job

Endpoint

Description

Parameters

Example Request

2. Show Jobs

Endpoint

Description

Example Request

3. Show Job by Job ID

Endpoint

Description

Path Parameters

Example Request

Understanding File Names and Date Ranges

File Naming Convention

Example Scenario

Key Points

Contact Support