Analytics API

Use the Analytics API to export raw records for AI customer service conversations from your Airgentic service.

Before You Start

You need:

Your account ID
Your service ID
An Insights API key created on the Security screen

The API key must be passed in the api-key request header.

Endpoint

Use the following endpoint:

GET https://admin.airgentic.com/api/insights/raw

This endpoint returns the raw analytics records for a single Airgentic service over a date range.

Query Parameters

Parameter	Required	Description
`account_id`	Yes	Your Airgentic account ID
`service_id`	Yes	The service ID to query
`start_date`	Yes	Start date in `YYYY-MM-DD` format
`end_date`	No	End date in `YYYY-MM-DD` format. If omitted, the API uses `start_date`

Date handling:

start_date is inclusive
end_date is inclusive
Dates are interpreted in UTC

Request Header

Header	Required	Description
`api-key`	Yes	The Insights API key from the Security screen

Example Request

curl -H "api-key: <API Key>" \
  "https://admin.airgentic.com/api/insights/raw?account_id=<account ID>&service_id=<service ID>&start_date=2026-01-01&end_date=2026-01-20"

For a single day, you can omit end_date:

curl -H "api-key: <API Key>" \
  "https://admin.airgentic.com/api/insights/raw?account_id=<account ID>&service_id=<service ID>&start_date=2026-01-20"

Response Format

The response is a JSON object with request metadata and a data array of raw analytics records:

{
  "account_id": "bcit",
  "service_id": "web",
  "start_date": "2026-01-01",
  "end_date": "2026-01-20",
  "record_count": 2,
  "data": [
    {
      "account_id": "bcit",
      "service_id": "web",
      "partition_id": "bcit_web",
      "date_time": "2026-01-20T03:14:15.123456+00:00",
      "browser_url": "https://www.example.com/help",
      "session_id": "8b4d6c57-8b5a-4b1d-a442-6a85e7e3958c",
      "user_id": "GA1.1.123456789.1234567890",
      "thread_id": "9f5901d0-5da2-4b92-b587-3f83d58640d6",
      "opening_question": "How do I reset my password?",
      "lang": "en-AU",
      "thread_concluded": true,
      "thread_chat_history": "...",
      "full_chat_history": null,
      "city": "Vancouver",
      "region": "British Columbia",
      "country": "Canada",
      "latitude": 49.2827,
      "longitude": -123.1207,
      "expert_agent": "default",
      "citation_urls": [
        "https://www.example.com/help/reset-password"
      ],
      "billable": true,
      "moderated_hate": "Safe",
      "moderated_selfharm": "Safe",
      "moderated_sexual": "Safe",
      "moderated_violence": "Safe",
      "completeness": "Full",
      "sentiment": "Neutral",
      "product": null,
      "class_custom1": false,
      "class_custom2": null,
      "class_custom3": null,
      "class_custom4": null,
      "class_custom5": null,
      "user_rating": "Good",
      "question_type": null,
      "error_code": null,
      "needs_review": false,
      "standalone_question_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "taxonomies": [
        {
          "taxonomy_key": "topics",
          "taxonomy_name": "Topics",
          "categories": [
            {
              "node_key": "billing.refunds",
              "label": "Refunds",
              "path": ["Billing", "Refunds"],
              "is_primary": true,
              "rank": 1
            }
          ]
        }
      ],
      "cluster": {
        "cluster_id": "b2c3d4e5-0000-0000-0000-000000000002",
        "label": "Password reset issues",
        "period_month": "2026-01"
      },
      "theme": {
        "theme_id": "c3d4e5f6-0000-0000-0000-000000000003",
        "label": "Account Access"
      }
    }
  ]
}

Records are returned in descending order by date_time (newest first).

Record Fields

Each record in data can include the following fields:

Field	Description
`account_id`	Account ID for the record
`service_id`	Service ID for the record
`partition_id`	Internal partition key, usually `<account_id>_<service_id>`
`date_time`	Timestamp of the record in ISO 8601 format
`browser_url`	Page URL where the conversation originated
`session_id`	Session ID for the visitor session
`user_id`	Optional external user identifier, if configured and captured
`thread_id`	Conversation thread ID
`previous_thread_id`	Previous thread ID when a thread continues from an earlier one
`opening_question`	The first question asked in the thread
`lang`	Browser or conversation language
`thread_concluded`	Whether the thread was concluded
`thread_chat_history`	Raw chat history for the thread
`full_chat_history`	Full multi-thread chat history when available
`city`	Detected city of the user
`region`	Detected region or state
`country`	Detected country
`latitude`	Latitude of detected location
`longitude`	Longitude of detected location
`expert_agent`	Specialist agent that handled the conversation
`citation_urls`	URLs cited in the AI answer
`billable`	Whether the interaction counted as billable
`moderated_hate`	Hate-safety moderation result
`moderated_selfharm`	Self-harm moderation result
`moderated_sexual`	Sexual-content moderation result
`moderated_violence`	Violence moderation result
`completeness`	Whether the answer was complete, partial, or unanswered
`sentiment`	Detected user sentiment
`product`	Product associated with the conversation, when available
`class_custom1` to `class_custom5`	Internal custom classification fields
`user_rating`	User feedback such as thumbs up or thumbs down
`question_type`	Optional classified question type
`error_code`	Internal error code, if an error occurred
`needs_review`	Whether the interaction has been flagged for review
`standalone_question_id`	Internal ID linking the record to semantic clustering and taxonomy data; `null` if not yet assigned
`taxonomies`	Array of published taxonomy assignments for this question; each item has `taxonomy_key`, `taxonomy_name`, and `categories` (see below). Empty array if none
`cluster`	Cluster (“topic”) for this question in the completed clustering run whose calendar month matches the record’s `date_time`; `null` if none. Includes `cluster_id`, `label`, and `period_month` (`YYYY-MM`)
`theme`	Canonical theme mapped to that cluster; `null` if the cluster has no theme mapping

Taxonomy structure: A service may have multiple published taxonomies. Within one taxonomy, a question may be assigned to multiple categories (multi-label). Each category object includes:

node_key — Stable key for the category node
label — Display label for the assigned node
path — Labels from the root of the taxonomy tree down to this node (hierarchical taxonomies)
is_primary and rank — Hints when several categories apply (lower rank is more relevant)

Cluster and month: cluster is chosen using the month of date_time (UTC). For example, a record dated 2026-01-15 uses the cluster from the January (2026-01) clustering run for your service, if that run completed successfully.

Common Errors

Status	Meaning
`400 Bad Request`	A date parameter is invalid. Use `YYYY-MM-DD`
`401 Unauthorized`	The `api-key` header is missing or invalid
`403 Forbidden`	The Insights API is not enabled for this service
`404 Not Found`	The account/service combination was not found
`500 Internal Server Error`	Airgentic could not retrieve the records

Notes

The API returns raw analytics records related to AI customer service conversations.
Historical records may contain null values for fields that were added after the conversation took place.
taxonomies, cluster, and theme depend on clustering and taxonomy pipelines; older exports may show empty taxonomies, or null for cluster / theme, until those jobs have run.
The API is designed for programmatic export and downstream reporting, not for interactive filtering in the browser.

Help