API

Use the REST API to access your development and production observability data from any environment: scripts, dashboards, CI pipelines, or custom integrations.

Prerequisites

A Context Company account with at least one project sending data
An API key (generated in the next step)

Setup

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.

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

List runs
Get a run

GET /v1/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 the native column populated from `tcc.agent`.
`userId` / `external_user_id`	string	No	Exact external user ID. Matches the native column populated from `tcc.userId`.
`orgId` / `external_org_id`	string	No	Exact external organization / customer ID. Matches the native column populated from `tcc.orgId`. This is the customer’s ID in your system, not the Context Company 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.

Parameter	Type	Required	Description
`source`	`"dev"` \| `"prod"`	Yes	Data source

curl "https://api.thecontext.company/v1/runs/abc123?source=prod" \
  -H "Authorization: Bearer <your-api-key>"

Sessions

List sessions
Get a session

GET /v1/sessions

Parameter	Type	Required	Description
`range` / `from` + `to`	string	Yes	Time range
`limit`	number	No	Max results (default 50, max 200)
`offset`	number	No	Pagination offset
`agent`	string	No	Exact agent name. Matches the native column populated from `tcc.agent`.
`userId` / `external_user_id`	string	No	Exact external user ID. Matches the native column populated from `tcc.userId`.
`orgId` / `external_org_id`	string	No	Exact external organization / customer ID. Matches the native column populated from `tcc.orgId`. This is the customer’s ID in your system, not the Context Company platform org ID.

curl "https://api.thecontext.company/v1/sessions?range=2w&limit=10" \
  -H "Authorization: Bearer <your-api-key>"

GET /v1/sessions/:sessionId

Returns the full session conversation including messages, detected patterns, and tool calls.

curl "https://api.thecontext.company/v1/sessions/session-xyz" \
  -H "Authorization: Bearer <your-api-key>"

Metrics

GET /v1/metrics

Returns aggregate metrics including run count, duration, tokens, and cost.

Parameter	Type	Required	Description
`range` / `from` + `to`	string	Yes	Time range

curl "https://api.thecontext.company/v1/metrics?range=1M" \
  -H "Authorization: Bearer <your-api-key>"

Models

GET /v1/models

Returns a breakdown of model usage across your runs.

curl "https://api.thecontext.company/v1/models?range=2w" \
  -H "Authorization: Bearer <your-api-key>"

Tools

GET /v1/tools

Returns a breakdown of tool usage across your runs.

curl "https://api.thecontext.company/v1/tools?range=2w" \
  -H "Authorization: Bearer <your-api-key>"

Failures

List failures
Get a failure

GET /v1/failures

Returns 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

curl "https://api.thecontext.company/v1/failures?range=1d&order_by=events&direction=desc" \
  -H "Authorization: Bearer <your-api-key>"

GET /v1/failures/:failureId

Returns detail for a specific failure pattern.

curl "https://api.thecontext.company/v1/failures/fail-123" \
  -H "Authorization: Bearer <your-api-key>"

Feedback

Get feedback metrics
List runs with feedback

GET /v1/feedback

Returns user feedback metrics over a time range.

curl "https://api.thecontext.company/v1/feedback?range=1M" \
  -H "Authorization: Bearer <your-api-key>"

GET /v1/feedback/runs

Parameter	Type	Required	Description
`range` / `from` + `to`	string	Yes	Time range
`limit`	number	No	Max results (default 50, max 200)
`offset`	number	No	Pagination offset

curl "https://api.thecontext.company/v1/feedback/runs?range=2w&limit=10" \
  -H "Authorization: Bearer <your-api-key>"

Patterns

The patterns, insights, and insight search endpoints require a Pro or Enterprise plan.

List patterns
List runs by pattern

GET /v1/patterns

Returns detected patterns such as frustration, confusion, and other behavioral signals.

Parameter	Type	Required	Description
`range` / `from` + `to`	string	Yes	Time range

curl "https://api.thecontext.company/v1/patterns?range=2w" \
  -H "Authorization: Bearer <your-api-key>"

GET /v1/patterns/:slug/runs

Parameter	Type	Required	Description
`range` / `from` + `to`	string	Yes	Time range
`limit`	number	No	Max results (default 50, max 200)
`offset`	number	No	Pagination offset

curl "https://api.thecontext.company/v1/patterns/user-frustration/runs?range=1M&limit=20" \
  -H "Authorization: Bearer <your-api-key>"

Insights

List weekly insights
Get an insight

GET /v1/insights

Returns auto-generated weekly insights.

curl "https://api.thecontext.company/v1/insights" \
  -H "Authorization: Bearer <your-api-key>"

GET /v1/insights/:id

curl "https://api.thecontext.company/v1/insights/insight-456" \
  -H "Authorization: Bearer <your-api-key>"

Insight search

Insight search requires the monitoring feature on your plan.

POST /v1/insight-search

Ask natural-language questions about your production data. See insight search for more on 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?"}'

Getting started

Supported frameworks

Custom Instrumentation

Monitoring

Integrations

Security

Prerequisites

Setup

Authentication

Common parameters

Endpoints

Runs

Sessions

Metrics

Models

Tools

Failures

Feedback

Patterns

Insights

Insight search

​Prerequisites

​Setup

​Authentication

​Common parameters

​Endpoints

​Runs

​Sessions

​Metrics

​Models

​Tools

​Failures

​Feedback

​Patterns

​Insights

​Insight search

Prerequisites

Setup

Authentication

Common parameters

Endpoints

Runs

Sessions

Metrics

Models

Tools

Failures

Feedback

Patterns

Insights

Insight search