---
title: "Poll an agent execution"
method: GET
path: "/v1/agent/runs/{runId}"
tags: ["Agent Execution"]
---

# Poll an agent execution

`GET /v1/agent/runs/{runId}`

## Request

- Base URL: `https://api.marketintell.ai`
- URL: `https://api.marketintell.ai/v1/agent/runs/{runId}`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Return a tenant-owned run's state. Pending/running responses include Retry-After and retry_after_ms. Completed responses contain AgentExecutionEnvelope in data.result.

## Path parameters

- `runId` string, uuid, required

## Response `200`

Current execution state

- object
  - `success` true
  - `data` object
    - `contract_version` '1.0'
    - `run_id` string, uuid
    - `status` 'pending' | 'running' | 'completed' | 'failed' | 'canceled'
    - `result` AgentExecutionEnvelope
      - `contract_version` '1.0', required: Version of the transport-neutral agent execution contract.
      - `execution_id` string, required: Stable correlation id for this execution.
      - `status` 'completed', required
      - `session_id` string, uuid, required
      - `content` string, required
      - `structured_output` object, nullable
      - `disclaimer` string, required
      - `timestamp` string, date-time, required
      - `intent` string
      - `specialists_used` string[], required
      - `latency_ms` number, required
      - `classification` object, nullable
      - `correlation` object, nullable
      - `fact_projection` object: Neutral facts and thesis projection when evidence was requested.
      - `degradation` object: Present when a requested T2/T3 path fell back to T1.
      - `reasoning_summary` object, required: Safe evidence/decision summary. This is not hidden chain-of-thought and never contains model scratchpads.
        - `kind` 'evidence_summary', required
        - `disclosure` string, required
        - `intent` string, nullable, required
        - `domain` string, nullable, required
        - `tokens` string[], required
        - `timeframe` string, nullable
        - `specialists` string[], required
        - `quality` object, nullable, required: Bounded reasoning outcome and evidence-coverage metrics; never hidden chain-of-thought or scratchpads.
          - `direction` string, required
          - `confidence` number, required
          - `verification_score` number, required
          - `convergence` string, required
          - `fact_count` integer, required
          - `cited_fact_count` integer, required
          - `chain_count` integer, required
          - `tension_count` integer, required
          - `uncited_number_count` integer, required
        - `evidence` object, required
          - `fact_count` integer, required
          - `must_cite_fact_ids` string[], required
          - `facts` object[], required
        - `uncertainty` object, required
          - `alignment` string, nullable
          - `score` number, nullable
          - `confirming` string[]
          - `contradicting` string[]
      - `provenance` object, required
        - `sources` string[], required
        - `cited_facts` object[], required
      - `delivery` object, required
        - `transport` 'rest' | 'mcp' | 'a2a' | 'internal', required
        - `requested_mode` 'auto' | 'deep', required
        - `requested_tier` 't2' | 't3' | 'null', nullable
        - `delivered_tier` 't1' | 't2' | 't3' | 'null', nullable
        - `degraded` boolean, required
      - `recovery` object, nullable, required: Machine-actionable retry guidance when delivery degraded.
    - `error` object, nullable
    - `retry_after_ms` integer

## Other responses

- `404`: Run not found or owned by another key

---

[API](https://skmtc.dev/marketintell/apis/marketintell-api.md) · [All operations](https://skmtc.dev/marketintell/apis/marketintell-api/llms.txt) · [OpenAPI document](https://skmtc.dev/marketintell/apis/marketintell-api/revisions/f3ef87afc41f?raw)