---
title: "List runs"
method: GET
path: "/agent/runs"
tags: ["Agent"]
---

# List runs

`GET /agent/runs`

List Agent runs for your team, ordered from newest to oldest.

## Query parameters

- `limit` integer — Number of results per page
- `cursor` string — Agent run ID. New run IDs are returned with the `agent_run_` prefix.

## Response `200`

Paginated Agent runs

- AgentRunList
  - `object` 'list', required
  - `data` AgentRun[], required
    - `id` string, required — Agent run ID. New run IDs are returned with the `agent_run_` prefix.
    - `object` 'agent_run', required
    - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required
    - `stopReason` 'schema_satisfied' | 'budget_reached' | 'error' | 'cancelled', required
    - `createdAt` string, date-time, required — When the run was created
    - `completedAt` string, date-time, nullable, required
    - `request` AgentRunRequest, required — Canonicalized request fields stored with the run.
      - `query` string — Natural-language question or instructions for the request.
      - `systemPrompt` string — Additional instructions that guide generated output or agent behavior. Use this for source preferences, novelty constraints, duplication constraints, or other behavior guidance.
      - `input` object
        - `data` object[] — Records the agent should process or enrich.
        - `exclusion` object[] — Records or entities the agent should avoid returning.
      - `outputSchema` object, nullable — JSON Schema for validated structured output in `output.structured`. Fields unsupported by evidence may be returned as `null`. Supports draft-07, 2019-09, and 2020-12 via `$schema`.
      - `effort` 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'auto' | 'max' — Cost and reasoning effort preference for the run. `auto` lets Exa choose the appropriate effort. `max` is the highest-effort public beta tier for work where completeness and thoroughness matter more than latency or cost, including large list building, deep multi-source research, and criteria that are hard to verify.
      - `previousRunId` string — Agent run ID. New run IDs are returned with the `agent_run_` prefix.
      - `metadata` object — Caller-provided key-value metadata for your own tracking.
      - `dataSources` AgentDataSourceOutput[] — Exa Connect data providers configured for the run.
        - `provider` 'fiber' | 'financial_datasets' | 'similarweb' | 'baselayer' | 'affiliate' | 'particle' | 'jinko', required — Identifier of an Exa Connect data provider.
      - `budget` AgentBudgetOutput — Optional per-run spending limit for the metered `auto` and `max` efforts. Runs that finish early may cost less than the limit.
        - `maxCostDollars` number — Maximum amount this run can spend in US dollars. Accepts $1–$100 and applies only to `auto` and `max`; when omitted, the default cap is $5 for `auto` and $20 for `max`.
    - `output` AgentRunOutput, required
      - `text` string, required — Natural-language answer or summary.
      - `structured` union, required — Any JSON value.
        - boolean
        - number
        - string
        - JsonValue[]
        - object
      - `grounding` AgentGrounding[], required — Field-level citations emitted by the run.
        - `field` string, required — Output field the citations support.
        - `citations` AgentCitation[], required
          - `url` string, uri, required — Source URL.
          - `title` string — Source title.
        - `confidence` 'low' | 'medium' | 'high', nullable — Model-reported reliability for this field.
    - `usage` AgentUsage, required
      - `agentComputeUnits` number, required
      - `searches` integer, required
      - `emails` integer, required
      - `phoneNumbers` integer, required
      - `dataSources` AgentDataSourceUsage — Per-provider tool call counts for Exa Connect data sources used during the run. Keys are provider names (e.g. `fiber`, `similarweb`). Only providers with non-zero usage are included.
    - `costDollars` AgentCostDollars, required
      - `total` number, required
      - `agentCompute` number, required
      - `search` number, required
      - `emails` number, required
      - `phoneNumbers` number, required
      - `dataSources` AgentDataSourceCost — Per-provider cost in dollars for Exa Connect data sources used during the run. Keys are provider names (e.g. `fiber`, `similarweb`). Only providers with non-zero usage are included.
  - `hasMore` boolean, required — Whether there are more results
  - `nextCursor` string, required — Agent run ID. New run IDs are returned with the `agent_run_` prefix.

## Other responses

- `400` — Invalid request.
- `401` — Team context or authentication was not found.
- `500` — Server error or run timeout.

---

[API](https://skmtc.net/exa/apis/exa-public-api.md) · [All operations](https://skmtc.net/exa/apis/exa-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/exa/exa-public-api/revisions/5c7114e0ef43/schema)