API documentation - Bot Analytics Export

The All Events Dump API returns the raw, event-level data behind Bot Analytics — every user message, the bot's response, whether it was handled, the session it belonged to, and the user's profile fields. Use it to feed your own data warehouse, BI tool or reporting pipeline instead of exporting from the dashboard by hand.

The API is region-specific: you call the authentication and analytics hosts of the region your workspace is hosted in.

How it works

1. Create an API credential in the Admin Console with the Read Analytics Data scope.
2. Generate an access token from your region's authentication URL.
3. Call the analytics endpoint for your region with the access token, a date range and pagination parameters.
4. Page through the results until you have fetched all records.

Step 1: Create an API credential

1. In the Admin Console, go to API credentials.
2. Click Add credentials.
3. Enter an Auth name (up to 50 characters) — name it after the consuming system, for example Snowflake – bot events.
4. In Allowed scope, select Read Analytics Data.
5. Click Create credentials.
6. Copy the Client ID, Client secret, Username and Password, and store them in a secure location such as a secrets manager.

Step 2: Choose your regional base URLs

Use the Auth URL to generate tokens and the Analytics URL to fetch data. Both must belong to the same region — a token issued in one region is not valid in another.

In the examples below, replace <AUTH_URL> and <ANALYTICS_URL> with the values for your region.

Step 3: Generate an access token

Send a POST request to your region's token endpoint. The Authorization header is HTTP Basic auth built from clientId:clientSecret, Base64-encoded. The username and password go in the request body.

Endpoint

POST <AUTH_URL>/api/v1.0/oauth/token

Request

curl --location '<AUTH_URL>/api/v1.0/oauth/token' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <base64(clientId:clientSecret)>' \
  --data '{
    "username": "<username>",
    "password": "<password>",
    "grant_type": "password"
  }'

Response — 200 OK

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800,
  "refresh_token": "82e2cbfa-4d1a-42fc-857e-7da2faad7b70"
}

For more on grant types, refresh tokens and credential rotation, see API credentials – token generation.

Step 4: Fetch all events

Endpoint

GET <ANALYTICS_URL>/api/analytics/query/external

Headers

You don't need to pass a bot ID. The workspace is identified from the access token.

Query parameters

Request

curl -G '<ANALYTICS_URL>/api/analytics/query/external' \
  --header 'Authorization: Bearer <access_token>' \
  --data-urlencode 'metricId=botAnalytics:allEventsDump' \
  --data-urlencode 'isCustomMetric=true' \
  --data-urlencode 'responseType=table' \
  --data-urlencode 'from=2026-01-01' \
  --data-urlencode 'to=2026-02-01' \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=100'

Response — 200 OK

The example below is shortened to one column definition and one event.

{
  "isSuccess": true,
  "result": {
    "current": 1,
    "page": 1,
    "limit": 10,
    "total": 47668,
    "isManageColumnsEnabled": true,
    "columns": [
      {
        "key": "userMessage",
        "label": "User message",
        "type": "number",
        "sortable": true,
        "isDynamicColumn": false,
        "isMandatory": false,
        "isVisible": true,
        "sticky": false
      }
    ],
    "tableData": [
      {
        "employeeId": "EMP1024",
        "userMessage": "How many leaves do I have left?",
        "botResponse": "You have 12 days of annual leave remaining.",
        "timestamp": "Jan 14 2026, 3:08 PM",
        "utcTimestamp": "Jan 14 2026, 9:38 AM",
        "messageType": "plainText",
        "isHandled": "true",
        "isSurveyResponse": "false",
        "sessionId": "69676978e4451ee81cc38d48",
        "isEffective": "true",
        "returningUser": "false",
        "rating": "",
        "gptRequestId": "",
        "handledSubcategory": "",
        "skills": "",
        "articles": "",
        "Channel": "slack",
        "eventId": "6967640ed690eb787a38a218",
        "firstName": "Alex",
        "lastName": "Morgan",
        "email": "[email protected]",
        "displayName": "Alex Morgan"
      }
    ]
  }
}

Response columns

Each event in tableData contains the following fields. Use the Key column to read values from each row. Keys are case-sensitive: note that Channel starts with a capital letter.

Event fields

These fields are always present.

Handled Subcategory values

User profile fields

After the event fields, each event includes the user's profile fields. Which fields appear depends on your workspace's user profile configuration, so the set varies between workspaces. For example:

Read result.columns to get the exact list of fields for your workspace. Fields that aren't filled in for a user are returned as "".

For definitions of sessions, interactions and handled queries, see the Bot Analytics glossary.

Paginating through results

Results are paginated. To fetch all events for a date range:

1. Request page=1 with your chosen limit.
2. Read result.total and calculate the number of pages: ceil(total / limit).
3. Request each following page by incrementing page until you have fetched all pages.

Errors

Related pages

• API credentials
• API credentials – token generation
• Bot Analytics glossary
• Exports