---
title: "Get Agent Run"
method: GET
path: "/agent/runs/{run_id}"
tags: ["Agent"]
---

# Get Agent Run

`GET /agent/runs/{run_id}`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/agent/runs/{run_id}`
- Auth: HTTP bearer

Fetch one run.

THE ONE ROUTE HERE THAT IS NOT PURE DELEGATION, because there is no
`GET /v1/agent/work-items/{id}` on the JWT surface to call. Without it a
builder can create a run, receive its id, and then have no way to poll it
except by listing everything and filtering client-side.

Its visibility rule is copied from `list_work_items`, NOT from
`cancel_work_item`: a read may see the caller's own runs plus org-wide
`visibility='shared'` ones, whereas cancel is owner-only because stopping
someone else's work is destructive. Pinning the read to the stricter rule
would hide a shared run that the list route shows, and the two disagreeing
about the same row is worse than either answer alone.

404, never 403, on a run the caller may not see: a non-owner must not be
able to use this route to probe which runs exist in the org. Same reason
`cancel_work_item` returns 404 for a non-owner.

## Path parameters

- `run_id` string, uuid, required: Run ID

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Response `200`

Successful Response

- ApiResponseAgentRunResponse
  - `data` AgentRunResponse, required: One run. Identical shape whether read from the list or on its own.
    - `work_item_id` string, required
    - `session_id` string, nullable
    - `title` string, required
    - `agent_id` string, required
    - `entry_point` string, nullable
    - `status` string, required
    - `current_step` string, nullable
    - `next_action` string, nullable
    - `visibility` string, required
    - `credits_spent` integer
    - `credit_budget` integer, nullable
    - `created_at` string, required
    - `updated_at` string, required
    - `completed_at` string, nullable
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

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