UXA Data Export Service API

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:

• Set up a secure connection to the Hermes Messaging Service with a defined topic ACL for the uxa.sn_uxa_data_export.data_export_results topic set to Read Only.
• Configure two Kafka consumer processes with bootstrap addresses, the uxa.sn_uxa_data_export.data_export_results topic, and your keystore and truststore. Use the same Consumer Group ID for both processes. The consumer port ranges (typically 4100–4103 and 4200–4203) must be open to consume messages from a Hermes topic. Verify the consumer ports by navigating to Hermes Messaging Service > Diagnostics.
• Configure the SSL connection to Hermes in the consumer properties files using the truststore and keystore that you generated.
• Consume messages from the Hermes topic using a Python consumer or Kafka CLI. For more information, see Usage Insights Data Export — How to consume the results from Hermes? [KB3135555]. Messages must be consumed within the 36 hour retention window, after which they expire 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

Headers

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

Authorization: Bearer <access-token>

Status codes

Response body parameters (JSON)

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

"result": {
   "error": "String", 
   "message": "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.

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

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