---
title: "Get run"
method: GET
path: "/v1/projects/{project_id}/runs/{run_id}"
tags: ["runs"]
---

# Get run

`GET /v1/projects/{project_id}/runs/{run_id}`

## Request

- Base URL: `https://api.connic.co`
- URL: `https://api.connic.co/v1/projects/{project_id}/runs/{run_id}`
- Auth: HTTP bearer

Returns one run with its input, output, error, execution trace, token usage and cost, connector, trigger details and run context. Token usage and cost cover the agent's own model calls; judge evaluations of the run are listed by `GET /runs/{run_id}/judge-runs`.

Required permission: `runs.view`.

## Path parameters

- `project_id` string, uuid, required
- `run_id` string, uuid, required

## Query parameters

- `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

- AgentRunWithTraces: One run with its content, execution trace, token usage and cost.
  - `id` string, uuid, required
  - `agent_name` string, required: Base agent name; runs handled by an A/B variant are stored under the base name.
  - `test_name` string, nullable: A/B test variant that handled the run, or the test case name for `deploy_gate` runs; null for runs of the base agent.
  - `ab_test_ids` string[]: IDs of the A/B tests this run was counted in.
  - `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`.
  - `input` string, nullable: Run input as text, with the environment's redacted keys masked; null after the run is deleted.
  - `output` string, nullable: Final agent output, with the environment's redacted keys masked; null until the run finishes and after it is deleted.
  - `error` string, nullable: Failure or cancellation message, if any; null after the run is deleted.
  - `queued_at` string, date-time, required: When the run was created.
  - `started_at` string, date-time, nullable: When execution began; null until the run starts.
  - `ended_at` string, date-time, nullable: When the run reached a final status; null while it is active.
  - `duration_ms` number, nullable: 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: When the run's content and trace were deleted; null if they were not. Status, usage and cost remain.
  - `can_delete_data` boolean: True when the run and its background processing (usage accounting, judge evaluations, outbound deliveries) have finished, so it can be deleted.
  - `scheduled_at` string, date-time, nullable: When a scheduled run is due to start; null for runs queued immediately.
  - `queued_reason` string, nullable: Why a queued run has not started yet, for example `concurrency_wait`, `credit_exhausted` or `budget_limit_exceeded:<spend alert ID>`. Null once the run starts.
  - `token_usage` PublicRunTokenUsageResponse, required
    - `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.
    - `model_usages` PublicModelTokenUsageResponse[], required: Usage of each model request, in call order.
      - `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.
      - `model` string, nullable, required: Model that served the request. Null when not recorded.
  - `traces` AgentTraceResponse[]: Execution trace: spans and log entries ordered by `start_time`, then `span_order`. Empty after the run is deleted.
    - `id` string, uuid, required
    - `run_id` string, uuid, required: ID of the run this entry belongs to.
    - `name` string, required: Span name, or the log source for `log` entries, such as `log:system` or `log:tool:<tool name>`.
    - `type` 'span' | 'log', required: `span` for a timed step such as a model or tool call; `log` for a log line written during the run.
    - `status` string, required: Span outcome; a value containing `ERROR` (any case) marks a failed span. For `log` entries, the log level: `debug`, `info`, `warning` or `error`.
    - `inputs` string, nullable, required: Step input as text, with the environment's redacted keys masked.
    - `outputs` string, nullable, required: Step output as text, with the environment's redacted keys masked. For `log` entries, the log message.
    - `thoughts` string, nullable, required: Model reasoning text for the step, when the model returns it.
    - `start_time` string, date-time, required: When the step started or the log line was written.
    - `end_time` string, date-time, nullable, required: When the span ended; null for `log` entries and unfinished spans.
    - `duration_ms` number, nullable, required: Span duration in milliseconds; null for `log` entries.
    - `metadata` object, required: Additional span attributes as key-value pairs; empty for `log` entries.
    - `span_order` integer, required: Recording order within the run; breaks ties between equal `start_time` values.
    - `span_id` string, nullable, required: Span identifier, unique within the run.
    - `parent_span_id` string, nullable, required: `span_id` of the enclosing span; null for top-level spans and `log` entries.
  - `connector` ConnectorInfo: Connector whose event started a run.
    - `id` string, uuid, required
    - `name` string, required
    - `type` string, required: Connector type, such as `http` or `cron`.
  - `triggered_by` string, nullable: ID of the run whose agent started this run; older runs may hold a free-text value instead.
  - `triggered_by_run` TriggeredByRunInfo: The run whose agent started this run.
    - `id` string, uuid, required
    - `agent_name` string, required: Agent of the parent run.
  - `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.
  - `deployment_id` string, uuid, nullable: ID of the deployment that ran this run; null until the run is picked up.
  - `token_cost` PublicTokenCostResponse: 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.
  - `run_context` object, nullable: Context values stored by the run's middleware and tools, with the environment's redacted keys masked; null after the run is deleted.
  - `session` RunSessionInfo: Persistent session a run belongs to.
    - `session_id` string, required: Session ID, unique within the app name and user.
    - `app_name` string, required: Agent application name that owns the session.
    - `user_id` string, required: Agent user identity the session belongs to.
  - `guardrail_interventions` PublicGuardrailInterventionResponse[]: Guardrail checks that warned about, 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.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the required permission or access to the environment.
- `404`: The resource does not exist in this project.
- `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)