curl --silent --show-error --fail-with-body --request GET \
--url 'https://api.example.com/api/telemetry' \
--header 'x-widget-token: YOUR_API_KEY'
{
"ok": true,
"generatedAt": "2026-08-31T14:22:05Z",
"telemetry": {
"orgId": "string",
"agentId": "string",
"requests": 1,
"errors": 1,
"kbHits": 1,
"kbMisses": 1,
"avgLatencyMs": 250,
"lastLatencyMs": 250,
"lastRequestAt": "2026-08-31T14:22:05Z",
"tokens": {
"prompt": 1,
"completion": 1,
"total": 102,
"estimated": 1,
"samples": 1
},
"last": {}
}
}
In-memory request telemetry for an org/agent
Snapshot of the process-local telemetry counters. The org id comes only from the verified widget token…
GET
/
api
/
telemetry
curl --silent --show-error --fail-with-body --request GET \
--url 'https://api.example.com/api/telemetry' \
--header 'x-widget-token: YOUR_API_KEY'
{
"ok": true,
"generatedAt": "2026-08-31T14:22:05Z",
"telemetry": {
"orgId": "string",
"agentId": "string",
"requests": 1,
"errors": 1,
"kbHits": 1,
"kbMisses": 1,
"avgLatencyMs": 250,
"lastLatencyMs": 250,
"lastRequestAt": "2026-08-31T14:22:05Z",
"tokens": {
"prompt": 1,
"completion": 1,
"total": 102,
"estimated": 1,
"samples": 1
},
"last": {}
}
}
Snapshot of the process-local telemetry counters. The org id comes only from the verified
widget token; a request org (
x-org-id, orgId) is ignored, and without a token org the
route answers 401 unauthorized (outside production, STATESET_ORG_ID is a logged
fallback). Disabled deployments (STATESET_TELEMETRY_ENABLED=false)
answer 404 telemetry_disabled. The context field (resolved agent configuration) is
stripped before the snapshot is returned.
Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership. See the authentication and recovery guide for credential and retry rules.
Query parameters
Ignored by the analytics routes (telemetry, response review, thread analytics): their org comes only from the verified widget token, and they answer
401 unauthorized without one (outside production, STATESET_ORG_ID is a logged fallback). Kept for older clients.Agent id hint (also
agent_id, or header x-agent-id). Overridden by the widget token when present; must match it.Response
object
Process-local counters for one org/agent.
last (most recent request summary) is present when requests were seen; its shape is not fixed here.Status codes
| Code | Meaning |
|---|---|
200 | Telemetry snapshot |
401 | Widget token missing, malformed, expired, from the future, or badly signed |
403 | Request org/agent disagrees with the widget token claims |
404 | Telemetry disabled on this deployment |
429 | Too many requests for this IP (scoped by verified org/agent) |
500 | Unhandled error |
Using this contract
Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.curl --silent --show-error --fail-with-body --request GET \
--url 'https://api.example.com/api/telemetry' \
--header 'x-widget-token: YOUR_API_KEY'
{
"ok": true,
"generatedAt": "2026-08-31T14:22:05Z",
"telemetry": {
"orgId": "string",
"agentId": "string",
"requests": 1,
"errors": 1,
"kbHits": 1,
"kbMisses": 1,
"avgLatencyMs": 250,
"lastLatencyMs": 250,
"lastRequestAt": "2026-08-31T14:22:05Z",
"tokens": {
"prompt": 1,
"completion": 1,
"total": 102,
"estimated": 1,
"samples": 1
},
"last": {}
}
}
Last modified on November 13, 2026