> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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…

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

**orgId** `string`

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.

**agentId** `string`

Agent id hint (also `agent_id`, or header `x-agent-id`). Overridden by the widget token when present; must match it.

### Response

`object`

**ok** `boolean` *required*

Fixed value: `true`.

**generatedAt** `string (date-time)` *required*

**telemetry** `TelemetrySnapshot` *required*

Process-local counters for one org/agent. `last` (most recent request summary) is present when requests were seen; its shape is not fixed here.

**TelemetrySnapshot**

**orgId** `string,null` *required*

**agentId** `string,null` *required*

**requests** `integer` *required*

**errors** `integer` *required*

**kbHits** `integer` *required*

**kbMisses** `integer` *required*

**avgLatencyMs** `number` *required*

**lastLatencyMs** `number` *required*

**lastRequestAt** `string,null (date-time)` *required*

**tokens** `object` *required*

**tokens**

**prompt** `integer`

**completion** `integer`

**total** `integer`

**estimated** `integer`

**samples** `integer`

**last** `object,null`

### 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](https://docs.stateset.com/spec/chat-widget.json) for declared schemas and alternatives.
This page also includes documented corrections from the [spec overlays](https://github.com/stateset/docs/tree/main/spec/overlays).
Example IDs and values are illustrative; replace them with records from your workspace.

```bash cURL theme={null}
curl --silent --show-error --fail-with-body --request GET \
  --url 'https://api.example.com/api/telemetry' \
  --header 'x-widget-token: YOUR_API_KEY'
```

```json 200 theme={null}
{
  "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": {}
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.