> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecontextcompany.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API
> Query your observability data programmatically using the Context Company REST 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](https://thecontext.company) account with at least one project sending data
* An API key (generated in the next step)
## Setup
Go to the [Access Data page](https://www.thecontext.company/prod/mcp-and-api?mode=api) 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.
All endpoints live under `https://api.thecontext.company/v1`. Pass your key as a Bearer token:
```bash theme={null}
curl "https://api.thecontext.company/v1/runs?source=prod&range=1d&limit=10" \
-H "Authorization: Bearer "
```
## Authentication
Every request requires a `Bearer` token in the `Authorization` header:
```
Authorization: Bearer
```
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
```bash theme={null}
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`](/concepts#agents). |
| `userId` / `external_user_id` | string | No | Exact external user ID. Matches the native column populated from [`tcc.userId`](/concepts#user-and-organization-identity). |
| `orgId` / `external_org_id` | string | No | Exact external organization / customer ID. Matches the native column populated from [`tcc.orgId`](/concepts#user-and-organization-identity). This is the customer's ID in your system, **not** the Context Company platform org ID. |
```bash theme={null}
curl "https://api.thecontext.company/v1/runs?source=prod&range=1d&limit=5" \
-H "Authorization: Bearer "
```
```bash theme={null}
GET /v1/runs/:runId
```
Returns a single run with all steps and tool calls.
| Parameter | Type | Required | Description |
| --------- | ------------------- | -------- | ----------- |
| `source` | `"dev"` \| `"prod"` | Yes | Data source |
```bash theme={null}
curl "https://api.thecontext.company/v1/runs/abc123?source=prod" \
-H "Authorization: Bearer "
```
### Sessions
```bash theme={null}
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`](/concepts#agents). |
| `userId` / `external_user_id` | string | No | Exact external user ID. Matches the native column populated from [`tcc.userId`](/concepts#user-and-organization-identity). |
| `orgId` / `external_org_id` | string | No | Exact external organization / customer ID. Matches the native column populated from [`tcc.orgId`](/concepts#user-and-organization-identity). This is the customer's ID in your system, **not** the Context Company platform org ID. |
```bash theme={null}
curl "https://api.thecontext.company/v1/sessions?range=2w&limit=10" \
-H "Authorization: Bearer "
```
```bash theme={null}
GET /v1/sessions/:sessionId
```
Returns the full session conversation including messages, detected patterns, and tool calls.
```bash theme={null}
curl "https://api.thecontext.company/v1/sessions/session-xyz" \
-H "Authorization: Bearer "
```
### Metrics
```bash theme={null}
GET /v1/metrics
```
Returns aggregate metrics including run count, duration, tokens, and cost.
| Parameter | Type | Required | Description |
| ----------------------- | ------ | -------- | ----------- |
| `range` / `from` + `to` | string | Yes | Time range |
```bash theme={null}
curl "https://api.thecontext.company/v1/metrics?range=1M" \
-H "Authorization: Bearer "
```
### Models
```bash theme={null}
GET /v1/models
```
Returns a breakdown of model usage across your runs.
```bash theme={null}
curl "https://api.thecontext.company/v1/models?range=2w" \
-H "Authorization: Bearer "
```
### Tools
```bash theme={null}
GET /v1/tools
```
Returns a breakdown of tool usage across your runs.
```bash theme={null}
curl "https://api.thecontext.company/v1/tools?range=2w" \
-H "Authorization: Bearer "
```
### Failures
```bash theme={null}
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 |
```bash theme={null}
curl "https://api.thecontext.company/v1/failures?range=1d&order_by=events&direction=desc" \
-H "Authorization: Bearer "
```
```bash theme={null}
GET /v1/failures/:failureId
```
Returns detail for a specific failure pattern.
```bash theme={null}
curl "https://api.thecontext.company/v1/failures/fail-123" \
-H "Authorization: Bearer "
```
### Feedback
```bash theme={null}
GET /v1/feedback
```
Returns user feedback metrics over a time range.
```bash theme={null}
curl "https://api.thecontext.company/v1/feedback?range=1M" \
-H "Authorization: Bearer "
```
```bash theme={null}
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 |
```bash theme={null}
curl "https://api.thecontext.company/v1/feedback/runs?range=2w&limit=10" \
-H "Authorization: Bearer "
```
### Patterns
The patterns, insights, and insight search endpoints require a **Pro** or **Enterprise** plan.
```bash theme={null}
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 |
```bash theme={null}
curl "https://api.thecontext.company/v1/patterns?range=2w" \
-H "Authorization: Bearer "
```
```bash theme={null}
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 |
```bash theme={null}
curl "https://api.thecontext.company/v1/patterns/user-frustration/runs?range=1M&limit=20" \
-H "Authorization: Bearer "
```
### Insights
```bash theme={null}
GET /v1/insights
```
Returns auto-generated weekly insights.
```bash theme={null}
curl "https://api.thecontext.company/v1/insights" \
-H "Authorization: Bearer "
```
```bash theme={null}
GET /v1/insights/:id
```
```bash theme={null}
curl "https://api.thecontext.company/v1/insights/insight-456" \
-H "Authorization: Bearer "
```
### Insight search
Insight search requires the monitoring feature on your plan.
```bash theme={null}
POST /v1/insight-search
```
Ask natural-language questions about your production data. See [insight search](/features/insight-search) for more on what you can ask.
```bash theme={null}
curl -X POST "https://api.thecontext.company/v1/insight-search" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"query": "What are the most common failure patterns this week?"}'
```