# List Team Runs (/reference-api/schema/teams/list-team-runs)

## Team storage and identity [#team-storage-and-identity]

Use the database-backed [example Team server](/reference-api/schema/teams/create-team-run#example-team-server). Keep the Team run's returned `run_id` and `session_id`; a nested member run is not interchangeable with the Team run. Stored run, checkpoint and session operations require the configured database.

JWT user isolation is opt-in; non-admin service-account PAT callers always self-scope. Scoped callers need their own matching Team session and run, while configured resource authorization also applies. Run and checkpoint lookups return **404** for inaccessible or mismatched records. For factories, retain any `factory_input` needed by endpoints that reconstruct the Team.

The response is a **bare array** of Team run projections, without pagination metadata. These projections use `run_input` and ISO 8601 `created_at`; the raw single-run polling response uses a different representation.

Pass `session_id` and optionally an exact uppercase status: `PENDING`, `RUNNING`, `COMPLETED`, `ERROR`, `PAUSED`, `CANCELLED` or `REGENERATED`. Lowercase or unknown strings currently match nothing and return an empty array. Remote Team run listing is unsupported (**400**).

## `GET /teams/{team_id}/runs`

**Summary:** List Team Runs

**Description:** List runs for a team within a session, optionally filtered by status.

Useful for monitoring background runs and viewing run history.

### Authentication

- Option 1: `HTTPBearer` — HTTP bearer

### Parameters
- `team_id` (path; string; required)
- `session_id` (query; string; required) — Session ID to list runs for
- `status` (query; string | null; optional) — Filter by run status (PENDING, RUNNING, COMPLETED, ERROR)

### Request body

None.

### Responses

#### `200`

List of runs retrieved successfully

**`application/json`**

Type `unspecified`.

#### Other responses

- `400` — Bad Request `application/json`: Schema `BadRequestResponse` (object).
- `401` — Unauthorized `application/json`: Schema `UnauthenticatedResponse` (object).
- `404` — Team not found `application/json`: Schema `NotFoundResponse` (object).
- `422` — Validation Error `application/json`: Schema `ValidationErrorResponse` (object).
- `500` — Internal Server Error `application/json`: Schema `InternalServerErrorResponse` (object).