--- title: "List runs" method: GET path: "/v1/projects/{project_id}/runs" tags: ["stats"] --- # List runs `GET /v1/projects/{project_id}/runs` ## Request - Base URL: `https://api.connic.co` - URL: `https://api.connic.co/v1/projects/{project_id}/runs` - Auth: HTTP bearer Paginated run list for one environment. Narrow results with `status_filter`, `agent_name`, `trigger_source`, `deployment_id`, a preset `time_range`, or custom `start_date` and `end_date`; time filters apply to when runs were queued. Pass `session_id`, `session_app_name`, and `session_user_id` together to match one exact persistent session. `search` matches run ID, agent name, input, output and error text; it also accepts filter expressions like `context.customer == 'acme'`. Ordered by `sort_by` (`queued`, `duration`, `tokens`) in `sort_dir` direction; defaults to queue time, newest first. `projection=summary` leaves out `connector_id`, `ab_test_ids`, `input`, `output`, `error` and `triggered_by`; callers without the `runs.view` permission always get the summary projection. `include_total=false` skips counting and returns `total: null`. Required permission: `stats.view`. ## Path parameters - `project_id` string, uuid, required ## Query parameters - `environment_id` string, uuid, required: Environment to list runs from - `deployment_id` string, uuid, nullable: Only runs executed by this deployment. - `time_range` '1h' | '6h' | '24h' | '7d' | '30d' | 'today' | 'this_month' | 'last_month' | 'this_year', nullable: Preset window ending now, or a calendar period in UTC. Ignored when both `start_date` and `end_date` are set. - `start_date` string, date-time, nullable: Custom window start; applies only together with `end_date` and overrides `time_range`. - `end_date` string, date-time, nullable: Custom window end; applies only together with `start_date`. - `status_filter` RunStatus[], nullable: Only runs in these statuses. - `guardrail_outcome` string[], nullable: Only runs with at least one guardrail intervention of these outcomes. - `agent_name` string, nullable: Only runs of this agent. - `trigger_source` 'manual' | 'connector' | 'agent' | 'deploy_gate': How a run was started: `manual` by a user, `connector` by an inbound connector event, `agent` by another agent, or `deploy_gate` as a deployment test run. - `test_name` string[], nullable: Filter by A/B test variant names; use __base__ for runs without a variant - `exclude_test_runs` boolean: Exclude runs with a test name - `search` string, nullable: Text matched against run ID, agent name, input, output and error, or a filter expression. - `session_id` string, nullable: Persistent session ID; requires `session_app_name` and `session_user_id`. - `session_app_name` string, nullable: Agent application name of the session; requires `session_id`. - `session_user_id` string, nullable: Agent user identity of the session; requires `session_id`. - `sort_by` 'queued' | 'duration' | 'tokens': Column to sort by - `sort_dir` 'asc' | 'desc': Sort direction - `limit` integer: Page size, 1 to 250. - `offset` integer: Number of runs to skip. - `projection` 'full' | 'summary': `full` returns every run field; `summary` leaves out the content fields. - `include_total` boolean: Include the filtered total count - `convert_costs_to` 'EUR' | 'USD', nullable: Convert token costs to EUR or USD at the daily ECB reference rate of each model call ## Response `200` Successful Response - PublicRunListResponse - `runs` PublicRunListItemResponse[], required: Runs on this page. - `id` string, uuid, required - `deployment_id` string, uuid, nullable, required: Deployment that ran the agent. Null when none is recorded. - `agent_name` string, required: Agent the run belongs to. - `test_name` string, nullable, required: A/B test variant that handled the run. Null for the base agent. - `status` 'scheduled' | 'queued' | 'started' | 'awaiting_approval' | 'completed' | 'failed' | 'cancelled' | 'blocked', required: Run state: `scheduled` until its start time, `queued`, `started` while executing, `awaiting_approval` while paused for a human decision, then `completed`, `failed` or `cancelled`. - `queued_at` string, date-time, nullable, required: When the run entered the queue. - `started_at` string, date-time, nullable, required: When execution began. Null while the run is scheduled or queued. - `ended_at` string, date-time, nullable, required: When the run finished. Null while it is still active. - `duration_ms` number, nullable, required: Execution time in milliseconds, excluding time spent waiting for approvals or child runs. Null until the run ends. - `data_deleted_at` string, date-time, nullable, required: When the run was deleted. Its input, output, error and traces are removed; status, timing and usage remain. - `can_delete_data` boolean, required: Whether the run can be deleted now: it and its background processing have finished and it is not deleted yet. - `token_usage` PublicTokenUsageResponse, required: Token counts summed over model calls. - `input_tokens` integer, required: Prompt tokens sent to the model, including cached tokens. - `output_tokens` integer, required: Tokens the model generated, excluding thinking tokens. - `cached_input_tokens` integer, required: Part of `input_tokens` read from the provider's prompt cache. - `thinking_tokens` integer, required: Reasoning tokens the model generated. - `total_tokens` integer, required: Input, output and thinking tokens combined. - `audio_input_tokens` integer: Part of `input_tokens` that was audio. - `audio_output_tokens` integer: Part of `output_tokens` that was audio. - `audio_cached_input_tokens` integer: Part of `cached_input_tokens` that was audio. - `audio_thinking_tokens` integer: Part of `thinking_tokens` that was audio. - `audio_usage_missing` boolean: True when at least one model call did not report its audio breakdown, so audio counts may be too low. - `token_cost` PublicTokenCostResponse, required: Token cost in each model's pricing currency, or in one currency when `convert_costs_to` is set. - `amounts` object, required: Total cost keyed by currency code (`EUR` or `USD`), as a decimal string with 12 decimal places. Only currencies with a nonzero amount are included. - `breakdown` object, required: Cost split by token type and by agent versus judge, keyed by currency code. - `coverage` PublicTokenCostCoverageResponse, required: How many model calls could be priced. - `complete` boolean, required: True when every model call could be priced. - `call_count` integer, required: Model calls covered by the report. - `priced_call_count` integer, required: Calls included in the cost amounts. - `unpriced_call_count` integer, required: Calls without a known price or without reported token usage. They are left out of the amounts. - `unpriced_models` string[], required: Models of the unpriced calls. - `converted_to` string, nullable: Currency the amounts were converted to at the daily ECB reference rate of each call. Present only when `convert_costs_to` is set. - `native_amounts` object, nullable: Totals in each model's pricing currency before conversion, as decimal strings keyed by currency code. Present only when `convert_costs_to` is set. - `scheduled_at` string, date-time, nullable, required: Time the run is scheduled to start. Null for runs that were not scheduled. - `guardrail_interventions` PublicGuardrailInterventionResponse[], required: Guardrail rules that warned, blocked or redacted content during the run. - `id` string, nullable - `name` string, nullable: Name of the custom guardrail. Null for built-in types. - `type` string, nullable: Guardrail type, such as `prompt_injection`, `pii`, `moderation`, `topic_restriction`, `regex` or `custom`. - `direction` string, nullable: `input` when the rule checked the run input, `output` when it checked the agent output. - `mode` string, nullable: Action configured for the rule: `block`, `warn` or `redact`. - `status` 'warned' | 'blocked' | 'redacted', required: Outcome: `warned` let the content through with a warning, `blocked` stopped it, `redacted` removed the matched content. - `message` string, nullable: Explanation from the guardrail. Empty after the run is deleted. - `connector_id` string, uuid, nullable: Connector that triggered the run. Null for other triggers; omitted with `projection=summary`. - `ab_test_ids` string[]: A/B tests the run was assigned to. Omitted with `projection=summary`. - `input` string, nullable: Input payload of the run. Null after the run is deleted; omitted with `projection=summary`. - `output` string, nullable: Final agent output. Null until the run completes or after it is deleted; omitted with `projection=summary`. - `error` string, nullable: Error message for runs that did not complete. Null otherwise; omitted with `projection=summary`. - `triggered_by` string, nullable: ID of the parent run when another agent started this run. Null otherwise; omitted with `projection=summary`. - `total` integer, nullable, required: Runs matching the filters across all pages. Null when `include_total=false`. - `limit` integer, required: Page size used. - `offset` integer, required: Number of runs skipped. ## Other responses - `401`: Missing or invalid API key. - `403`: The API key lacks the required permission or access to the environment. - `422`: Validation Error - `429`: Rate limit exceeded. --- [API](https://skmtc.dev/connic/apis/connic-api.md) · [All operations](https://skmtc.dev/connic/apis/connic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/connic/apis/connic-api/revisions/482932da5fbe?raw)