Bulk Data Export API

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.


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

Authorization

Userpilot API uses an API key to authenticate requests. You can find your API key on the Environment Page.

Your API key carries many privileges, so be sure to keep it secure! Do not share your secret API keys in publicly accessible areas.

Authentication Method:

Include your API key in the Authorization header:

Authorization: Token <your API key here>

💡 Note: All API requests must be made over HTTPS.

Rate Limits

Please note that the trigger 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.

💡 Note: To avoid missing important updates, we recommend providing a valid email address in the request. When the export data is ready, you will receive a notification via email with the download links. This helps ensure that you retrieve your data on time without needing to manually check the job status.

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.

Required Parameters

  • from (string): The start date of the export in YYYY-MM-DD format.
    • Example: "2024-05-02"
  • to (string): The end date of the export in YYYY-MM-DD format.
    • Example: "2024-09-30"

Optional Parameters

  • emails (array of strings): A list of valid email addresses to receive the exported data. If omitted, no email will be sent.
    • Example: ["example@work.com"]
  • event_type (array of strings): List of event types to filter the data. If not provided, the following default events are included:
    • "identify_user"
    • "identify_company"
    • "page_view"
    • "track"
    • "track_feature"
    • "interaction"
    • Example: ["track", "page_view"]
  • user_id (array of strings): List of specific user IDs to filter the data export. If omitted, all users are included.
    • Example: ["123456", "789012"]
  • company_id (array of strings): List of specific company IDs to filter the export. If omitted, all companies are included.
    • Example: ["13162551529"]
  • segment_id (string): Filter data based on a specific segment. If not provided, no segment filtering is applied.
    • Example: "987654"
  • format (string): The format of the exported data. Options are "json" (default) or "csv" .
    • Example: "csv"
  • exclusions (boolean, default: false ): Exclude users/companies you have set in the web app.

Example Request

curl --location '<https://appex.userpilot.io/api/v1/analytics/exports/>' \\
--header 'Authorization: Token <your API key here>' \\
--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
}'

Successful Response (201 Created)

If the export job is successfully created, the API will return a 201 Created status along with the following JSON response:

{
  "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",
}
  • environment_app_token : The token for the app environment.
  • environment_name : The name of the environment (e.g., production ).
  • job_id : Unique identifier for the export job.
  • links : API endpoint to check the status of the job.
  • start_time : Timestamp indicating when the job started.

Error Responses

  • Conflict (409 Conflict)

    If there is already an export job in progress, the API will return a 409 Conflict status with the following JSON error message:

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

  • Unauthorized (401 Unauthorized**)**

    If your account does not have permission to export data, the API will return a 403 Forbidden status with the following JSON error message:

{
    "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 <your API key here>'

Successful Response (200 OK)

On success, the API will return a 200 OK status with an array of job objects:

[
  {
    "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"
  },
  {
    "elapsed_time": "43 seconds",
    "elapsed_time_seconds": 43,
    "end_time": "2024-09-22T11:19:08.714898Z",
    "job_id": "862c0224-6359-47b3-9c67-00a86120e999",
    "progress": "6 out of 6 partitions",
    "start_time": "2024-09-22T11:18:25.683429",
    "status": "completed"
  }
]
  • elapsed_time : Human-readable time taken to complete the job (e.g., "44 seconds").
  • elapsed_time_seconds : Time taken to complete the job in seconds.
  • end_time : Timestamp indicating when the job completed.
  • job_id : Unique identifier for the export job.
  • progress : Current progress of the job (e.g., "2 out of 6 partitions").
  • start_time : Timestamp indicating when the job started.
  • status : Current status of the job (completed , in_progress , or failed ).

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

  • job_id (string): The unique identifier of the export job you want to retrieve.

Example Request

curl --location '<https://appex.userpilot.io/api/v1/analytics/exports/jobs/{job_id}>' \\
--header 'Authorization: Token <your API key here>'

Successful Response (200 OK)

On success, the API will return a 200 OK status with the following JSON response:

{
  "app_token": "<YOUR-APP-TOKEN>",
  "completed_chunks": [
    "2024-05-01",
    "2024-06-01",
    "2024-07-01",
    "2024-08-01",
    "2024-09-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://csvexports.userpilot.io/.../2024-07-29.json.gz?...&X-Amz-Signature=>..."
    },
    {
      "filename": "2024-08-05.json.gz",
      "url": "<https://csvexports.userpilot.io/.../2024-08-05.json.gz?...&X-Amz-Signature=>..."
    }
  ],
  "progress": "2 out of 5 partitions",
  "start_time": "2024-09-22T13:17:26.864860Z",
  "status": "completed",
  "all_chunks": [
    "2024-05-01",
    "2024-06-01",
    "2024-07-01",
    "2024-08-01",
    "2024-09-01"
  ],
  "type": "export"
}
  • app_token : The token for the app environment.
  • completed_chunks : An array of dates representing the chunks that have been completed.
  • current_chunk : The date of the chunk currently being processed.
  • end_time : Timestamp indicating when the job completed.
  • job_id : Unique identifier for the export job.
  • presigned_urls : An array of objects containing filenames and their corresponding pre-signed URLs for downloading.
    • filename : Name of the file to be downloaded.
    • url : Pre-signed URL for accessing the file.
  • progress : Current progress of the job (e.g., "2 out of 6 partitions").
  • start_time : Timestamp indicating when the job started.
  • status : Current status of the job (completed , in_progress , or failed ).
  • all_chunks : An array of dates representing all chunks that were processed.
  • type : Type of the job (e.g., "export" ).

💡 Note:

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

Error Response (404 Not Found)

If the specified job ID does not exist, the API will return a 404 Not Found status with the following JSON error message:

{
    "errors": [
        {
            "details": null,
            "error": "Resource not found",
            "error_code": "404",
            "message": "Failed to retrieve job with id ba111778-f28a-40ca-8c64-e83e2a3bb96ee for application NX-51f4acf7: job not found"
        }
    ]
}
  • errors : Indicates that the specified job ID does not correspond to any existing export job.

Notes

  • Replace <your API key here> with your actual API key in all requests.
  • Replace {job_id} with the actual job ID you wish to query.
  • Mandatory Fields: from and to parameters are required when triggering an export job.
  • Default Values:
    • event_type defaults to a list of common events 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" .

Lookups APIs

The Lookups APIs allow you to retrieve metadata about various entities in your Userpilot account, such as user properties, company properties, features, events, and more.

Endpoints

  • GET User Properties
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/user_properties>
  • GET Company Properties
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/company_properties>
  • GET Features & Events
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/features_events>
  • GET Trackable Events' Properties/Attributes (Paginated)
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/events_properties>
  • GET Segments(Paginated)
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/segments>
  • GET Flows (Experiences)
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/flows>
  • GET Banners
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/banners>
  • GET Spotlights
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/spotlights>
  • GET Surveys (with modules)
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/surveys>
  • GET Resource Center Modules
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/resource_center_modules>
  • GET Checklists (with Tasks)
GET <https://appex.userpilot.io/api/v1/analytics/exports/lookups/checklists>

Description

These endpoints allow you to fetch lists of your passed user/company properties, features, events, and other entities to assist in understanding your data.

Example Request

curl --location '<https://appex.userpilot.io/api/v1/analytics/exports/lookups/user_properties>' \\
--header 'Authorization: Token <your API key here>'

Successful Response (200 OK)

On success, the API will return a 200 OK status with a JSON array containing the requested data.

Pagination Overview (For Trackable Events' Properties/Attributes And Segments Lookups)

The response includes a cursor object within the metadata section. This object contains the information required for pagination:

  • after: This field contains the cursor for fetching the next set of results.
  • before: This field can be used to fetch previous results (if available).
  • limit: The number of results returned per request.
  • total_count: The total number of available records.

The response also provides:

  • data: The list of event properties Or Segments fetched by the current request.

Pagination Parameters

When calling this API, you can pass a after_cursor parameter in your query to paginate forward through the data. The value of this parameter should be the value of metadata.cursor.after from the previous response.

Example Request (Pagination Forward)

curl --location '<https://appex.userpilot.io/api/v1/analytics/exports/lookups/events_properties?after_cursor=g3QAAAADZAACaWR0AAAABGQACl9fc3RydWN0X19kAA5FbGl4aXIuRGVjaW1hbGQABGNvZWZhRWQAA2V4cGEAZAAEc2lnbmEBZAAQaXNfYXV0b19wcm9wZXJ0eWQABWZhbHNlZAAJbGFzdF9zZWVudAAAAA1kAApfX3N0cnVjdF9fZAAPRWxpeGlyLkRhdGVUaW1lZAAIY2FsZW5kYXJkABNFbGl4aXIuQ2FsZW5kYXIuSVNPZAADZGF5YRlkAARob3VyYQxkAAttaWNyb3NlY29uZGgCYQBhAGQABm1pbnV0ZWEtZAAFbW9udGhhCmQABnNlY29uZGErZAAKc3RkX29mZnNldGEAZAAJdGltZV96b25lbQAAAAdFdGMvVVRDZAAKdXRjX29mZnNldGEAZAAEeWVhcmIAAAfnZAAJem9uZV9hYmJybQAAAANVVEM=&limit=50>' \\
--header 'Authorization: Token <your API key here>'

Example Response

{
    "data": [
        {
            "category": null,
            "data_type": "string",
            "description": null,
            "display_name": "URL",
            "event": {
                "display_name": "All events",
                "id": null},
            "id": "-2",
            "inserted_at": "2023-08-16T09:22:44+03:00",
            "is_archived": false,
            "is_auto_property": true,
            "key": "url",
            "last_seen": "2024-09-29T13:11:32+03:00"
        },
        {
            "category": null,
            "data_type": "string",
            "description": null,
            "display_name": "Page",
            "event": {
                "display_name": "All events",
                "id": null}
        }
        ...
        ...
        ...
        ...
    ],
    "metadata": {
        "cursor": {
            "after": "g3QAAAADZAACaWR0AAAABGQACl9fc3RydWN0X19kAA5FbGl4aXIuRGVjaW1hbGQABGNvZWZhRWQAA2V4cGEAZAAEc2lnbmEBZAAQaXNfYXV0b19wcm9wZXJ0eWQABWZhbHNlZAAJbGFzdF9zZWVudAAAAA1kAApfX3N0cnVjdF9fZAAPRWxpeGlyLkRhdGVUaW1lZAAIY2FsZW5kYXJkABNFbGl4aXIuQ2FsZW5kYXIuSVNPZAADZGF5YRlkAARob3VyYQxkAAttaWNyb3NlY29uZGgCYQBhAGQABm1pbnV0ZWEtZAAFbW9udGhhCmQABnNlY29uZGErZAAKc3RkX29mZnNldGEAZAAJdGltZV96b25lbQAAAAdFdGMvVVRDZAAKdXRjX29mZnNldGEAZAAEeWVhcmIAAAfnZAAJem9uZV9hYmJybQAAAANVVEM=",
            "before": null},
        "limit": 50,
        "total_count": 53,
        "total_count_cap_exceeded": false}
}

Notes:

  • Always check if cursor.after exists in the response before making the next request.
  • If cursor.after is null , you have reached the last page of data.
  • To modify the number of results per request, use the limit parameter in your query string (default is 50).

Contact Support

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

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.