---
title: "List agent runs"
method: GET
path: "/v2/teamspaces/{teamspaceId}/sites/{siteId}/agent-runs"
tags: ["Docs7 Sites"]
---

# List agent runs

`GET /v2/teamspaces/{teamspaceId}/sites/{siteId}/agent-runs`

## Request

- Base URL: `https://context7.com/api`
- URL: `https://context7.com/api/v2/teamspaces/{teamspaceId}/sites/{siteId}/agent-runs`
- Auth: HTTP bearer

Runs of one agent, newest first: `improve` (Context7 Agent, default), `review` (PR Review Agent) or `watch` (Code Watch Agent). Any member. Only for GitHub sites: a CLI site (`source: "local"`) answers 404.

## Path parameters

- `teamspaceId` string, uuid, required
- `siteId` string, uuid, required

## Query parameters

- `history` 'improve' | 'review' | 'watch' | 'snippets'
- `limit` integer

## Response `200`

The runs

- object
  - `data` Docs7AgentRun[], required
    - `id` string, uuid, required
    - `siteId` string, uuid, required
    - `number` integer, required
    - `boxId` string
    - `baseBranch` string
    - `baseCommitSha` string
    - `state` 'running' | 'completed' | 'failed' | 'superseded', required
    - `trigger` 'schedule' | 'manual' | 'pull_request', required
    - `triggeredBy` string, nullable
    - `input` object, required: What the run worked on. The other fields depend on `kind`.
      - `kind` 'suggestions' | 'health' | 'feature_requests' | 'page_feedback' | 'migrate' | 'review' | 'code_change' | 'snippets', required
    - `pullRequest` object, nullable, required
      - `url` string, uri, required
      - `state` 'open' | 'closed' | 'merged' | 'unknown', required
    - `review` object, nullable: PR Review Agent result.
      - `findings` object[]
        - `check` 'brokenLinks' | 'grammar' | 'health' | 'standards'
        - `file` string, nullable
        - `line` integer, nullable
        - `message` string
        - `fixed` boolean
      - `commentUrl` string, uri, nullable
      - `commitSha` string, nullable
    - `snippets` object, nullable: Example Check Agent batches: the pages the batch checked and each code example's result. Null for other agents and while the batch runs.
      - `pages` string[]
      - `last` boolean: No page is left after these: the batch ended its check.
      - `blocks` object[], nullable
        - `file` string
        - `line` integer
        - `language` 'typescript' | 'javascript' | 'python'
        - `status` 'pass' | 'fail' | 'skipped'
        - `detail` string
        - `fixed` boolean
        - `removed` boolean: Taken off the page until the released SDK or the service supports what the page documents.
        - `needs` string[]: For an example skipped because a service has no variable: the environment variables it reads.
    - `cost` object, nullable
      - `inputTokens` number
      - `outputTokens` number
      - `cachedInputTokens` number
      - `tokenUsd` number
      - `computeUsd` number, nullable
      - `durationMs` number
    - `summary` string, nullable: The agent's final message.
    - `error` string, nullable
    - `createdAt` string, date-time, required
    - `completedAt` string, date-time, nullable, required

## Other responses

- `400`: Invalid `history` or `limit`
- `401`: Missing or invalid bearer
- `403`: Not a member, missing role, or an API key of another teamspace
- `404`: No such site in this teamspace
- `500`: Internal error

## Changes

- **2026-10-27** `2ead96d131a7`: 1 warning, 2 info
  - added the new `snippets` enum value to the `data/items/input/kind` response property for the response status `200`
  - added the new enum value `snippets` to the `query` request parameter `history`
  - added the optional property `data/items/snippets` to the response with the `200` status
- **2026-10-27** `42dae0e52557`: 1 warning
  - added the new `migrate` enum value to the `data/items/input/kind` response property for the response status `200`
- **2026-10-26** `86c04930b016`: 1 breaking, 1 info
  - for the `query` request parameter `limit`, default value `50` was added
  - for the `query` request parameter `limit`, the max was increased from `50.00` to `500.00`
- **2026-10-22** `e17589fd8767`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/context7/apis/context7-public-api/changes/v2/teamspaces/:teamspaceId/sites/:siteId/agent-runs/get.md)

---

[API](https://skmtc.dev/context7/apis/context7-public-api.md) - [All operations](https://skmtc.dev/context7/apis/context7-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/context7/apis/context7-public-api/revisions/945f7834fa8c?raw)