UXA Data Export Service API

  • Release version: Australia
  • Updated June 24, 2026
  • 7 minutes to read

    • The UXA Data Export Service API provides an endpoint to asynchronously export user experience analytics (UXA) data. The data export result is delivered in batches to a dedicated Hermes topic for your ServiceNow instance.

    For more information about UXA, see Usage Insights.

    Use cases:
    • Bring usage data from your ServiceNow instance into an external enterprise analytics or business intelligence tool so it can be reported alongside data from other sources.
    • Build end-to-end views of a user journey that spans the ServiceNow AI Platform and other systems.
    • Move large volumes of usage data on a recurring schedule, beyond what is supported by manual export.

    This API requires the Usage Insight Data Export application (sn_uxa_data_export), which is available on the ServiceNow Store. The calling user must have the sn_uxa_data_export.user role. For automated exports, create a dedicated user for the export service rather than assigning the role to a personal user.

    No manual Hermes topic setup is required. A dedicated topic (uxa.sn_uxa_data_export.data_export_results) is automatically created on the first export request.

    After the first call to this API, set up your Kafka client to consume the data from the Hermes topic:

    UXA Data Export Service - POST /sn_uxa_data_export/data_export

    Submits an asynchronous request to export user experience analytics (UXA) data. The data export result is delivered in batches to a dedicated Hermes topic.

    Important:
    Batch messages must be consumed by your Kafka client within the 36 hour retention window, after which they expire from the Hermes topic.

    URL format

    Versioned URL: /api/sn_uxa_data_export/{api_version}/data_export

    Supported request parameters

    Table 1. Path parameters
    Name Description
    api_version Required. Version of the endpoint to access. The current version is v1.
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (JSON)
    Name Description
    app_sys_id Sys_id of the UXA application to export data for.

    To retrieve this value, open the Network tab in your browser's developer tools and filter by metric.AppSysId is located in the request payload.

    Table: Usage Insights App [sys_analytics_app]

    Default: Data is exported for all UXA applications.

    Data type: String
    channel Name of the channel to export data for.
    Valid values:
    • AINativeExperience
    • Chat
    • CoreUI
    • Mobile
    • NowExperience
    • Web

    Default: Data is exported for all channels.

    Data type: String
    columns Required. List of columns to include in the export.
    Supported columns:
    • Name: Name of the event.
    • Timestamp: Date and time the event occurred.
    • InstanceUserIdHashed: A hashed, privacy-preserving identifier for the user associated with the event. For more information, see User privacy, tracking, and user consent management.
    • AppSysId: Sys_id of the UXA application the data is for.
    • SessionId: A unique identifier assigned to a continuous period of user activity, grouping together all the events that happen during that visit. It resets after a period of inactivity of 30 minutes or continuous activity for 4 hours, starting a new session.
    • Properties: Additional metadata attached to an event that captures details such as what the user interacted with, the type of interacting, or the language.

    Data type: Array
    data_source Required. The data to export. The only currently supported value is events. Events include user activity such as page views, clicks, and navigation.
    Note:
    Use the Usage Insights dashboard to view your event data.

    Data type: String
    from_date Required. Inclusive start of the export date range in ISO 8601 format, rounded to the nearest hour.

    The maximum supported date range, from start to end date, is 90 days.

    Data type: String
    name_filter Name of the event to export data for.

    Default: Data is exported for all events.

    Data type: String
    to_date Required. Exclusive end of the export date range in ISO 8601 format, rounded to the nearest hour.

    The maximum supported date range, from start to end date, is 90 days.

    Data type: String

    Headers

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json.
    Authorization HTTP basic authentication or OAuth bearer token.
    Basic authentication format:
    Authorization: Basic <base64-encoded-username:password>
    OAuth format:
    Authorization: Bearer <access-token>
    Content-Type Data format of the request body. Only supports application/json.
    Table 5. Response headers
    Header Description
    None

    Status codes

    Table 6. Status codes
    Status code Description
    202 Accepted. The export job was queued for processing.
    400 Bad Request. The request failed validation.
    Common reasons:
    • Request body is missing or malformed.
    • Invalid data source. The only supported source is events.
    • Unrecognized column. Valid columns are: Name, Timestamp, InstanceUserIdHashed, AppSysId, SessionId, Properties.
    • Duplicate column.
    • columns must be a non-empty array.
    • from_date is required and must be in ISO 8601 format, rounded to the nearest hour.
    • to_date is required and must be in ISO 8601 format, rounded to the nearest hour.
    • to_date must be after from_date.
    • Date range exceeds the maximum (90 days).
    • Hermes endpoints are not yet available. This can happen shortly after plugin activation.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    402 Quota exceeded. The monthly data export cap has been exceeded.
    403 Forbidden. The calling user does not have a required role. The sn_uxa_data_export.user role is required to call this API.
    429 Too Many Requests. The rate limit of 60 requests per hour has been exceeded. Retry after the rate-limit window resets.
    500 Internal server error. Data export is not configured on this instance. Contact your administrator to set the Valk Query Service URL.
    503 Service Unavailable. Retry with exponential backoff.

    Response body parameters (JSON)

    Name Description
    result Object containing information about the data export job.

    Success structure:

    "result": {
   "hermes_topic_endpoint": "String",
   "job_id": "String",
   "status": "String" 
}

    Error structure:

    "result": {
   "error": "String", 
   "message": "String"
}

    Data type: Object
    result.error Error code.

    Data type: String
    result.hermes_topic_endpoint The Hermes topic where the data export result is delivered in batches.

    Data type: String
    result.job_id Unique identifier for the export job.

    Each batch of data delivered to the Hermes topic contains the job_id for the job it belongs to.

    Data type: String
    result.message Error message.

    Data type: String
    result.status The status of the export request. A value of accepted means the export is queued for processing.

    Data type: String

    Data export batch message format

    The data export result is delivered asynchronously to the Hermes topic in batches. Each batch message contains the data in JSON format and carries enrichment headers.

    Table 7. Enrichment headers
    Header Description
    SNaction This value is always INITIAL, which indicates this is a bulk historical export rather than a live data feed.
    SNdata_seeding_time_UTC Date and time the data was queried in ISO 8601 format (UTC).
    SNinstance Name of the ServiceNow instance that initiated the export.
    SNorigin Origin of the message, which is sn_uxa_data_export.
    SNtableName The data source table, such as events.
    Table 8. Result message parameters (JSON)
    Name Description
    columns List of columns included in the export.

    Data type: Array
    creation_date Date and time the export job was created in ISO 8601 format (UTC).

    Data type: String
    from_date Inclusive start of the export date range contained in this batch in ISO 8601 format.

    Data type: String
    instance_id Unique identifier of the ServiceNow instance that initiated the export.
    job_id Unique identifier for the export job.

    Each batch of data delivered to the Hermes topic contains the job_id for the job it belongs to.

    Data type: String
    rows The exported data rows, LZ4-compressed and base64-encoded. Each data row is an array of values matching the column order defined in columns.
    To decode:
    1. Base64-decode the string.
    2. LZ4-decompress the result.
    3. JSON-parse to get an array of row arrays.
    Example of decoded, decompressed, and parsed rows when columns are ["Name", "Timestamp", "InstanceUserIdHashed"]:
    "rows": [
    ["click", "2025-01-15T10:00:00", "0762d92db72412103a248bdc4e24a527"],
    ["click", "2025-01-15T10:05:00", "5862c90db32522103a858cbb4e11a928"]
]

    Data type: String
    rows_encoding Encoding applied to the rows field. This value is always lz4+base64 (LZ4-compressed and base64-encoded).

    Data type: String
    subtask_num The sequence number of this batch (1-based indexing). When subtask_num equals total_subtasks, all batches have been delivered.

    Data type: Number
    to_date Exclusive end of the export date range contained in this batch in ISO 8601 format.

    Data type: String
    total_subtasks Total number of batches included in the export job.

    Data type: Number
    version Message format version. This value is always 1.0.

    For testing and troubleshooting, you can view batch messages in the Hermes Topic Inspector.

    cURL request

    This example exports click events recorded through the NowExperience channel for a single application during January 2025.

    curl "https://instance.service-now.com/api/sn_uxa_data_export/v1/data_export" \
--request POST \
--header 'Accept:application/json' \
--header 'Content-Type:application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
  "data_source": "events",
  "columns": ["Name", "Timestamp", "InstanceUserIdHashed"],
  "from_date": "2025-01-01T00:00:00",
  "to_date": "2025-02-01T00:00:00",
  "name_filter": "click",
  "channel": "NowExperience",
  "app_sys_id": "6735143c87c07610f13ebbf7ccbb35e1"
}' \
--user 'username':'password'

    Response body.

    {
  "result": {
    "job_id": "abc-123-def-456",
    "status": "accepted",
    "hermes_topic_endpoint": "snc.<instance>.uxa.sn_uxa_data_export.data_export_results"
  }
}

    Result batch message

    Result batch message 1 out of 10 for the export delivered asynchronously to the Hermes topic.

    {
   "version": "1.0",
   "job_id": "abc-123-def-456",
   "instance_id": "instance-id",
   "creation_date": "2025-06-01T12:00:00+00:00",
   "from_date": "2025-01-01T00:00:00",
   "to_date": "2025-02-01T00:00:00",
   "subtask_num": 1,
   "total_subtasks": 10,
   "columns": ["Name", "Timestamp", "InstanceUserIdHashed"],
   "rows_encoding": "lz4+base64",
   "rows": "<base64-encoded LZ4-compressed JSON array>"
}

    Decoded, decompressed, and parsed rows:

    "rows": [
   ["click", "2025-01-15T10:00:00", "0762d92db72412103a248bdc4e24a527"],
   ["click", "2025-01-15T10:05:00", "5862c90db32522103a858cbb4e11a928"]
]