Telemetry Endpoints

The Prism API serves telemetry queries from data landed by the worker for your organization.

GET /v1/telemetry/context

Latest context snapshot for a single Claude Code session, served from the newest API-request telemetry within the last 24 hours — used by the plugin to hydrate the working context on resume. Scoped to the authenticated developer (service principals without a delegated user are rejected).

GET /v1/telemetry/context?session_id=abc123
Authorization: Bearer gck_your_key

Parameter	Type	Required	Description
`session_id`	string	yes	Session to fetch the latest context for

An empty session_id returns 400 Bad Request. When no recent telemetry exists, the endpoint returns a well-formed “unavailable” context response rather than an error.

GET /v1/telemetry/logs

Query log records.

GET /v1/telemetry/logs?from=2024-01-01T00:00:00Z&to=2024-01-07T00:00:00Z&limit=100
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
`from`	ISO8601	24h ago	Start time
`to`	ISO8601	now	End time
`session_id`	string	—	Filter to a single session
`developer_id`	string	—	Filter to a single developer
`limit`	integer	100	Max records (max 1000)
`offset`	integer	0	Pagination offset

GET /v1/telemetry/metrics

Query metric data points. Same parameters as /logs.

GET /v1/telemetry/traces

Query trace spans. Same parameters as /logs.

GET /v1/telemetry/stats

Aggregated statistics grouped by time, session, or developer.

GET /v1/telemetry/stats?from=2024-01-01T00:00:00Z&to=2024-01-07T00:00:00Z&group_by=day&signal=logs
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
`from`	ISO8601	7 days ago	Start time
`to`	ISO8601	now	End time
`group_by`	enum	`hour`	One of `hour`, `day`, `session_id`, `developer_id`. Invalid values return `400`.
`signal`	enum	`logs`	One of `logs`, `metrics`, `traces`.

POST /v1/telemetry/per-turn

Query per-turn telemetry for a specific set of prompts or sessions (body-driven to avoid long query strings). Used by the dashboard’s session explorer to hydrate turn-by-turn detail.

POST /v1/telemetry/per-turn
Authorization: Bearer gck_your_key
Content-Type: application/json

{
  "session_id": "…",
  "prompt_ids": ["…"]
}

GET /v1/telemetry/analytics

Analytics with in-memory caching — tools used, errors, efficiency metrics.

GET /v1/telemetry/analytics?from=2024-01-01T00:00:00Z&to=2024-01-07T00:00:00Z&tz_offset=-300
Authorization: Bearer gck_your_key

Parameter	Type	Default	Description
`from`	ISO8601	7 days ago	Start time
`to`	ISO8601	now	End time
`tz_offset`	integer	`0`	Timezone offset in minutes east of UTC. Shifts event timestamps before bucketing so `day`/`hour` aggregates reflect local time. Example: `540` for KST, `-300` for EST.

Results are cached per org_id:from:to key for fast repeated queries.

POST /v1/telemetry/analytics/batch

Compute analytics for several time ranges in one request — the dashboard uses it to fetch, for example, “this week” and “last week” together instead of issuing serial calls. Each range carries a caller-supplied key that is echoed back on the matching result.

POST /v1/telemetry/analytics/batch
Authorization: Bearer gck_your_key
Content-Type: application/json

{
  "ranges": [
    { "key": "this_week", "from": "2024-01-08T00:00:00Z", "to": "2024-01-15T00:00:00Z" },
    { "key": "last_week", "from": "2024-01-01T00:00:00Z", "to": "2024-01-08T00:00:00Z" }
  ],
  "tz_offset": -300
}

Body field	Type	Default	Description
`ranges`	array	—	One `{ key, from, to }` object per range
`tz_offset`	integer	`0`	Timezone offset in minutes east of UTC
`timezone`	string	—	Optional IANA timezone name
`refresh`	boolean	`false`	Bypass the analytics cache

Response: { "results": [ { "key": "this_week", "analytics": { … } }, … ] } — each analytics value has the same shape as GET /v1/telemetry/analytics.

Compaction read safety

Telemetry compaction code is inactive by default (off) and also defines audit, write-retain, and raw-delete modes. This API reference does not prescribe or imply a rollout, configuration, or activation.

A corrupt or unreadable compaction authority or manifest, or an unavailable authority output, is incomplete or unavailable data. It is never represented as an empty Complete result.

Notes

Narrow the time range and filters as much as you can — the endpoints scan less and answer faster.
Data is partitioned by year/month/day/hour (Hive partitioning) — narrower time ranges are faster.
Results are scoped to the authenticated organization.