---
title: "GET /projects/{projectId}/agent-runs"
method: GET
path: "/projects/{projectId}/agent-runs"
---

# GET /projects/{projectId}/agent-runs

`GET /projects/{projectId}/agent-runs`

## Request

- Base URL: `https://api.caveman.so/api/v1`
- URL: `https://api.caveman.so/api/v1/projects/{projectId}/agent-runs`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/api/v1/oauth/authorize`
    - Token URL: `/api/v1/oauth/token` scopes: `trace:read_metadata`
  - HTTP bearer
  - API key in cookie `cave_access`
  - API key in cookie `__Secure-cave_identity.session_token`

GET /api/v1/projects/{projectId}/agent-runs on the Caveman Cloud control plane. Requires the trace:read_metadata scope. Not exposed to autonomous agents: Native user history of immutable owned chat runs. Shared agents use the protected journal. Native unscoped user endpoint. Returns only this user's owned chat run metadata. Results require separate current permission and source checks.

## Query parameters

- `after` string, uuid
- `sessions` boolean

## Response `200`

Bounded native user page.

- AgentRunPage
  - `data` AgentRunSummary[], required
    - `id` string, uuid, required
    - `case_id` string, uuid, required
    - `definition_id` string, required
    - `definition_version` string, required
    - `status` 'queued' | 'running' | 'completed' | 'incomplete' | 'cancelled' | 'stale', required
    - `reason` string, required
    - `created_at` string, date-time, required
    - `deadline` string, date-time, required
    - `model` string: The model the run was admitted on (provider/model); absent when the run stamped none (Factory and Sentinel stages).
  - `next_cursor` string, required: Run UUID cursor, or empty when no next page.

## Other responses

- `400`: Invalid cursor.
- `401`: Authentication required.
- `403`: Native user required.
- `404`: Project, cursor or current authority unavailable.
- `503`: Shared agent configuration unavailable.
- `4XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `5XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.

---

[API](https://skmtc.dev/caveman/apis/caveman-cloud-api.md) - [All operations](https://skmtc.dev/caveman/apis/caveman-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/caveman/apis/caveman-cloud-api/revisions/508312d01cfc?raw)