API
Prerequisites#
- A Context Company account with at least one project sending data
- An API key (generated below)
Setup#
Step 1: Generate a read-only API key
Go to the Access Data page in your dashboard and create a read-only API key. These keys (prefixed with tcc_key) can only query your data — they cannot ingest traces. Choose an access scope:
| Scope | Access |
|---|---|
| Dev only | Development runs and traces |
| Prod only | Production runs, metrics, patterns, failures, and sessions |
| Dev + Prod | All dev and production data |
Copy your key immediately. You won't be able to see it again. Read-only API keys are separate from the ingestion keys (prefixed with
tcc_prod) used to send traces from your AI application. Ingestion keys are managed in Settings by admins. Read-only keys can be created by any team member.
Step 2: Make your first request
All endpoints live under https://api.thecontext.company/v1. Pass your key as a Bearer token:
curl "https://api.thecontext.company/v1/runs?source=prod&range=1d&limit=10" \
-H "Authorization: Bearer <your-api-key>"Authentication#
Every request requires a Bearer token in the Authorization header:
Authorization: Bearer <your-api-key>
The key's scope determines which endpoints you can access. Dev-scoped keys can only query dev data, prod-scoped keys can only query prod data, and dev+prod keys can access both.
Common parameters#
Most endpoints accept time-range parameters:
| Parameter | Type | Description |
|---|---|---|
range |
string | Time preset: 5m, 1h, 1d, 2w, 1M, 2M (or verbose: last_5_minutes, last_hour, last_day, last_two_weeks, last_month, last_two_months) |
from |
string | Start time as ISO 8601 or ms timestamp. Use with to instead of range |
to |
string | End time as ISO 8601 or ms timestamp. Use with from instead of range |
You must provide either range or both from and to.
Endpoints#
Runs#
GET /v1/runs — list runs.
| Parameter | Type | Required | Description |
|---|---|---|---|
source |
dev | prod |
Yes | Data source to query |
range / from+to |
string | Yes | Time range |
limit |
number | No | Max results (default 50, max 200) |
status |
ok | error |
No | Filter by status (prod only) |
session_id |
string | No | Filter by session (prod only) |
agent |
string | No | Exact agent name — matches tcc.agent |
userId / external_user_id |
string | No | Exact external user ID — matches tcc.userId |
orgId / external_org_id |
string | No | Exact external org ID — matches tcc.orgId. This is the customer's ID in your system, not the TCC platform org ID. |
curl "https://api.thecontext.company/v1/runs?source=prod&range=1d&limit=5" \
-H "Authorization: Bearer <your-api-key>"GET /v1/runs/:runId — returns a single run with all steps and tool calls (requires source).
Sessions#
GET /v1/sessions — list sessions, same time-range/agent/user/org filters as runs, plus offset for pagination.
GET /v1/sessions/:sessionId — returns the full session conversation including messages, detected patterns, and tool calls.
Metrics#
GET /v1/metrics — aggregate metrics including run count, duration, tokens, and cost. Requires range or from+to.
curl "https://api.thecontext.company/v1/metrics?range=1M" \
-H "Authorization: Bearer <your-api-key>"Models#
GET /v1/models — breakdown of model usage across your runs.
Tools#
GET /v1/tools — breakdown of tool usage across your runs.
Failures#
GET /v1/failures — aggregated error patterns.
| Parameter | Type | Required | Description |
|---|---|---|---|
range / from+to |
string | Yes | Time range |
order_by |
events | first_seen | last_seen |
No | Sort order (default last_seen) |
direction |
asc | desc |
No | Sort direction |
entity_type |
run | tool_call |
No | Filter by entity type |
status |
active | resolved | ignored |
No | Filter by status |
GET /v1/failures/:failureId — detail for a specific failure pattern.
Feedback#
GET /v1/feedback — user feedback metrics over a time range.
GET /v1/feedback/runs — list runs with feedback (time range, limit, offset).
Patterns#
The patterns, insights, and insight search endpoints require a Pro or Enterprise plan.
GET /v1/patterns — detected patterns such as frustration, confusion, and other behavioral signals.
GET /v1/patterns/:slug/runs — runs matching a specific pattern (time range, limit, offset).
Insights#
GET /v1/insights — auto-generated weekly insights.
GET /v1/insights/:id — a specific insight.
Insight search#
POST /v1/insight-search — ask natural-language questions about your production data. See Insight search for what you can ask.
curl -X POST "https://api.thecontext.company/v1/insight-search" \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{"query": "What are the most common failure patterns this week?"}'