Overview
A read-only HTTPS API over the telemetry your Subcore agents produce.
Your agents ship telemetry to Subcore as they work: every customer turn, every model reply, every tool call. This API reads it back.
It is read-only. Four GET endpoints, one credential, one response envelope.
| Endpoint | Answers |
|---|---|
GET /telemetry/sessions | Which conversations happened, most recently active first |
GET /telemetry/sessions/{sid} | Everything that happened inside one conversation, in order |
GET /telemetry/events | Events across conversations, filtered by type, tool, agent or time |
GET /telemetry/runs/{runId} | Everything that happened inside one evaluation run |
Base URL: https://api.subcore.ai
Your first request
curl -H "Authorization: Bearer $SUBCORE_API_KEY" \
"https://api.subcore.ai/telemetry/sessions?limit=5"{
"items": [
{
"sid": "chat_01J9Z2K8QW",
"core_slug": "support-agent",
"channel": "chat",
"run_type": "production",
"first_at": "2026-09-03T14:02:11.418Z",
"last_at": "2026-09-03T14:09:52.006Z",
"event_count": 24
}
],
"nextCursor": "eyJrIjoic2Vzc2lvbnMiLCJ0IjoiMjAy..."
}Without a key you get a 401, which is also the quickest way to confirm you
have the right URL:
{
"error": "Missing Authorization header",
"code": "AUTHENTICATION_ERROR",
"timestamp": 1788566031707
}Conventions
Every list response is { items, nextCursor }. There are no other list
shapes. Paging is by opaque cursor, never by offset — see
pagination.
Everything is scoped to the key's organization. The scope is applied before any filter you send, so there is no request that can read across organizations.
Times are ISO 8601 strings, exactly as the database returned them. Filters
that take a time (from, to) accept any ISO 8601 value.
Cores are named by slug. A core is one deployed agent. coreSlug=support-agent
filters to that agent; omitting it spans every agent the key may read.
Rate limits
Reads are limited to 120 requests per minute per key by default, and every response carries the count:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the window |
X-RateLimit-Remaining | Requests left in this window |
Retry-After | Seconds until the window resets. Sent on a 429 only |
Over budget, you get a 429 with code: "RATE_LIMITED".
The limiter counts per server instance rather than globally, so the ceiling you actually observe can be higher than 120 when your traffic is spread across instances. Treat 120/min as the number to design against, not as a number to probe for. Telemetry ingestion is never rate limited; a deployment shipping events is not throttled because something else is paging through history.