UXA Data Export Service API

concept australia Updated Sep 10, 2026 8 min read usage-insight-data-exp-api.md
Raw file servicenow.com

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:

Parent Topic:REST API reference

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

Name Description
api_version Required. Version of the endpoint to access. The current version is v1.
Name Description
None

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

Header

Description

Accept

Data format of the response body. Only supports application/json.

Authorization

HTTP basic authentication or OAuth bearer token.Basic authentication format:

Text
Authorization: Basic <base64-encoded-username:password>

OAuth format:

Text
Authorization: Bearer <access-token>

Content-Type

Data format of the request body. Only supports application/json.
|Header|Description| |------|-----------| |None| |

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:

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

Error structure:

Text
"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.

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.

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"]:

JSON
"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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/view-messages-hermes-topic.md).

cURL request

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

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

JSON
{  "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.

JSON
{   "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:

JSON
"rows": [   ["click", "2025-01-15T10:00:00", "0762d92db72412103a248bdc4e24a527"],   ["click", "2025-01-15T10:05:00", "5862c90db32522103a858cbb4e11a928"]]
Search documentation
Search document titles and file paths on the australia branch