Userpilot Analytics Export API (appex)
Userpilot Analytics Export API for triggering and retrieving export jobs and looking up resources (segments, flows, surveys, banners, checklists, properties).
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Userpilot API",
"version": "1.0.0",
"termsOfService": "https://userpilot.io/terms-of-service/",
"description": "Userpilot's API suite for user identification, event tracking, data import/export, and user/company management.\n\nAuthentication:\n All endpoints that require authentication expect an HTTP header in the following format:\n\n Authorization: Token {{API_KEY}}\n\nExample (cURL):\n curl -X GET 'https://appex.userpilot.io/v1/identify' \\\n -H 'Authorization: Token abcd1234efgh5678' \\\n -H 'Content-Type: application/json'\n\nContact Support:\n Email: [email protected]",
"contact": {
"name": "Userpilot",
"url": "https://userpilot.io",
"email": "[email protected]"
},
"license": {
"name": "MIT",
"url": "https://opensource.org/licenses/MIT"
}
},
"servers": [
{
"url": "https://appex.userpilot.io",
"description": "Application endpoint"
}
],
"paths": {
"/api/v1/analytics/exports/jobs/{job_id}": {
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"description": "(Required) Unique identifier for the export job",
"example": "<uuid>",
"schema": {
"type": "string"
}
}
],
"get": {
"summary": "Show Job by Job ID",
"parameters": [
{
"name": "Accept",
"in": "header",
"required": false,
"example": "application/json",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"headers": {
"Content-Type": {
"schema": {
"type": "string"
},
"example": "application/json"
}
},
"description": "OK - Export job details",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"app_token": {
"type": "string"
},
"completed_chunks": {
"type": "array",
"items": {
"type": "string"
}
},
"current_chunk": {
"type": "string"
},
"end_time": {
"type": "string"
},
"job_id": {
"type": "string"
},
"presigned_urls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"filename": {
"type": "string"
},
"url": {
"type": "string"
}
}
}
},
"progress": {
"type": "string"
},
"start_time": {
"type": "string"
},
"status": {
"type": "string"
},
"all_chunks": {
"type": "array",
"items": {
"type": "string"
}
},
"type": {
"type": "string"
}
}
}
}
}
},
"401": {
"headers": {
"Content-Type": {
"schema": {
"type": "string"
},
"example": "application/json"
}
},
"description": "Unauthorized - Invalid API key",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"details": {
"type": "string"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}
},
"404": {
"headers": {
"Content-Type": {
"schema": {
"type": "string"
},
"example": "application/json"
}
},
"description": "Not Found - Export job not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"details": {
"type": "string"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
},
"/api/v1/analytics/exports/jobs/": {
"parameters": [],
"get": {
"summary": "Show Jobs",
"parameters": [
{
"name": "Accept",
"in": "header",
"required": false,
"example": "application/json",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"headers": {
"Content-Type": {
"schema": {
"type": "string"
},
"example": "application/json"
}
},
"description": "OK - List of export jobs",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"elapsed_time": {
"type": "string"
},
"elapsed_time_seconds": {
"type": "string"
},
"end_time": {
"type": "string"
},
"job_id": {
"type": "string"
},
"progress": {
"type": "string"
},
"start_time": {
"type": "string"
},
"status": {
"type": "string"
}
}
}
}
}
}
},
"401": {
"headers": {
"Content-Type": {
"schema": {
"type": "string"
},
"example": "application/json"
}
},
"description": "Unauthorized - Invalid API key",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"details": {
"type": "string"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/user_properties": {
"get": {
"summary": "Get user properties",
"description": "Retrieve a list of user properties available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of user properties.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"id": 1,
"type": "user_property",
"key": "email",
"display_name": "Email",
"data_type": "string",
"is_auto_property": false
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/company_properties": {
"get": {
"summary": "Get company properties",
"description": "Retrieve a list of company properties available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of company properties.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"id": 10,
"type": "company_property",
"key": "company_name",
"display_name": "Company Name",
"data_type": "string",
"is_auto_property": false
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/segments": {
"get": {
"summary": "Get segments",
"description": "Retrieve a paginated list of segments available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A paginated list of segments.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object"
}
},
"metadata": {
"type": "object",
"properties": {
"cursor": {
"type": "object",
"properties": {
"after": {
"type": "string",
"nullable": true
},
"before": {
"type": "string",
"nullable": true
}
}
},
"limit": {
"type": "integer"
},
"total_count": {
"type": "integer"
}
}
}
}
},
"example": {
"data": [
{
"id": 101,
"title": "Active Users",
"usage": "all",
"category": "user_id",
"is_hidden": false,
"is_protected": false,
"status": "published"
}
],
"metadata": {
"cursor": {
"after": "...",
"before": null
},
"limit": 50,
"total_count": 1
}
}
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/features_events": {
"get": {
"summary": "Get features & events",
"description": "Retrieve a list of features and events available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of features and events.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"display_name": "Feature A",
"key": "feature_a",
"data_type": "string"
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/events_properties": {
"get": {
"summary": "Get trackable events' properties/attributes (paginated)",
"description": "Retrieve a paginated list of trackable event properties and attributes. Supports cursor-based pagination.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
},
{
"name": "after_cursor",
"in": "query",
"required": false,
"schema": {
"type": "string"
},
"description": "Cursor for pagination. Use the value from the previous response's metadata.cursor.after."
}
],
"responses": {
"200": {
"description": "A paginated list of event properties.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object"
}
},
"metadata": {
"type": "object",
"properties": {
"cursor": {
"type": "object",
"properties": {
"after": {
"type": "string",
"nullable": true
},
"before": {
"type": "string",
"nullable": true
}
}
},
"limit": {
"type": "integer"
},
"total_count": {
"type": "integer"
}
}
}
}
},
"example": {
"data": [
{
"id": 12,
"key": "url",
"display_name": "URL",
"is_auto_property": true,
"is_mobile_auto_property": false,
"data_type": "string",
"category": "css_attribute",
"description": "Page URL",
"is_archived": false,
"event": {
"id": 33,
"display_name": "page_view"
},
"inserted_at": "2025-01-01T00:00:00Z",
"last_seen": "2025-01-10T00:00:00Z"
}
],
"metadata": {
"cursor": {
"after": "...",
"before": null
},
"limit": 50,
"total_count": 53
}
}
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/flows": {
"get": {
"summary": "Get flows (experiences)",
"description": "Retrieve a list of flows (experiences) available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of flows (experiences).",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"id": 123,
"title": "Onboarding Flow"
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/banners": {
"get": {
"summary": "Get banners",
"description": "Retrieve a list of banners available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of banners.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"id": 77,
"title": "Promo Banner"
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/embeds": {
"get": {
"summary": "Get embeds",
"description": "Retrieve a list of embeds (banners and cards) available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of embeds (banners and cards).",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"id": 77,
"title": "Promo Banner",
"type": "banner"
},
{
"id": 92,
"title": "Feature Card",
"type": "card"
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/spotlights": {
"get": {
"summary": "Get spotlights",
"description": "Retrieve a list of spotlights available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of spotlights.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"id": 88,
"title": "New Feature Spotlight"
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/surveys": {
"get": {
"summary": "Get surveys (with modules)",
"description": "Retrieve a list of surveys (with modules) available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of surveys (with modules).",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"id": 45,
"title": "CSAT Survey",
"platform": "web",
"modules": [
{
"id": 1,
"order": 1,
"type": "open_text",
"question": "How was it?"
}
]
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/resource_center_modules": {
"get": {
"summary": "Get resource center modules",
"description": "Retrieve a list of resource center modules available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of resource center modules.",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"display_name": "Resource Center Module A",
"key": "resource_center_module_a",
"data_type": "string"
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports/lookups/checklists": {
"get": {
"summary": "Get checklists (with tasks)",
"description": "Retrieve a list of checklists (with tasks) available for export.",
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"responses": {
"200": {
"description": "A list of checklists (with tasks).",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object"
}
},
"example": [
{
"display_name": "Checklist A",
"key": "checklist_a",
"data_type": "string"
}
]
}
}
}
}
}
},
"/api/v1/analytics/exports": {
"parameters": [
{
"$ref": "#/components/parameters/AuthorizationHeader"
}
],
"post": {
"summary": "Trigger an Export Job",
"parameters": [
{
"name": "Content-Type",
"description": "The content type of the request body. Must be `application/json`.",
"in": "header",
"required": false,
"example": "application/json",
"schema": {
"type": "string"
}
},
{
"name": "Accept",
"description": "The content type of the response body. Must be `application/json`.",
"in": "header",
"required": false,
"example": "application/json",
"schema": {
"type": "string"
}
}
],
"responses": {
"201": {
"headers": {
"Content-Type": {
"schema": {
"type": "string"
},
"example": "application/json"
}
},
"description": "Created - Export job successfully created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"environment_app_token": {
"type": "string",
"description": "The app token of the environment.",
"example": "NX-RE213S2"
},
"environment_name": {
"type": "string",
"description": "The name of the environment.",
"example": "production"
},
"job_id": {
"type": "string",
"description": "The ID of the export job.",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"links": {
"type": "string",
"description": "The links to the export job."
},
"start_time": {
"type": "string",
"description": "The start time of the export job."
}
}
}
}
}
},
"401": {
"headers": {
"Content-Type": {
"schema": {
"type": "string"
},
"example": "application/json"
}
},
"description": "Unauthorized - Invalid API key or insufficient permissions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"details": {
"type": "string"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}
},
"409": {
"headers": {
"Content-Type": {
"schema": {
"type": "string"
},
"example": "application/json"
}
},
"description": "Conflict - Export job already in progress",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"details": {
"type": "string"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"emails": {
"type": "array",
"items": {
"type": "string"
}
},
"event_type": {
"type": "array",
"items": {
"type": "string"
}
},
"user_id": {
"type": "array",
"items": {
"type": "string"
}
},
"company_id": {
"type": "array",
"items": {
"type": "string"
}
},
"segment_id": {
"type": "string"
},
"format": {
"type": "string",
"enum": [
"avro",
"csv",
"ndjson",
"parquet"
]
},
"exclusions": {
"type": "string"
}
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"AuthorizationHeader": {
"name": "Authorization",
"in": "header",
"required": true,
"description": "API authentication token in the format: `Token {{API_KEY}}`. Obtain your API key from the [Userpilot Environment Settings](https://run.userpilot.io/environment).",
"schema": {
"type": "string"
},
"example": "Token abcd1234efgh5678"
}
},
"schemas": {
"ErrorResponse": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"details": {
"type": "string",
"description": "Detailed error information."
},
"error": {
"type": "string",
"description": "Short error code or label."
},
"error_code": {
"type": "string",
"description": "Error code for programmatic handling."
},
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/userpilot/refs/heads/main/openapi/userpilot-appex-openapi.json