---
title: "List Runs"
method: GET
path: "/v1/runs/"
tags: ["runs"]
---

# List Runs

`GET /v1/runs/`

List all runs.

## Query parameters

- `agent_id` string, nullable — The unique identifier of the agent associated with the run.
- `agent_ids` string[], nullable — The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.
- `statuses` string[], nullable — Filter runs by status. Can specify multiple statuses.
- `background` boolean, nullable — If True, filters for runs that were created in background mode.
- `stop_reason` 'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'
- `before` string, nullable — Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order
- `after` string, nullable — Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order
- `limit` integer, nullable — Maximum number of runs to return
- `order` 'asc' | 'desc' — Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first
- `order_by` 'created_at' — Field to sort by
- `active` boolean — Filter for active runs.
- `ascending` boolean — Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field.

## Response `200`

Successful Response

- Run[]
  - `id` string — The human-friendly ID of the Run
  - `status` 'created' | 'running' | 'completed' | 'failed' | 'cancelled' — Status of the run.
  - `created_at` string, date-time — The timestamp when the run was created.
  - `completed_at` string, date-time, nullable — The timestamp when the run was completed.
  - `agent_id` string, required — The unique identifier of the agent associated with the run.
  - `background` boolean, nullable — Whether the run was created in background mode.
  - `metadata` object, nullable — Additional metadata for the run.
  - `request_config` LettaRequestConfig
    - `use_assistant_message` boolean — Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects.
    - `assistant_message_tool_name` string — The name of the designated message tool.
    - `assistant_message_tool_kwarg` string — The name of the message argument in the designated message tool.
    - `include_return_message_types` MessageType[], nullable — Only return specified message types in the response. If `None` (default) returns all messages.
  - `stop_reason` 'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'
  - `callback_url` string, nullable — If set, POST to this URL when the run completes.
  - `callback_sent_at` string, date-time, nullable — Timestamp when the callback was last attempted.
  - `callback_status_code` integer, nullable — HTTP status code returned by the callback endpoint.
  - `callback_error` string, nullable — Optional error message from attempting to POST the callback endpoint.
  - `ttft_ns` integer, nullable — Time to first token for a run in nanoseconds
  - `total_duration_ns` integer, nullable — Total run duration in nanoseconds

## Other responses

- `422` — Validation Error

## Changes

- **2025-10-07** `57161ea6ef83` — 1 info
  - added the new optional `query` request parameter `statuses`
- **2025-10-01** `2b1d21acfb81` — 1 breaking, 3 info
  - for the `query` request parameter `limit`, default value was changed from `50` to `100`
  - added the new optional `query` request parameter `order`
  - added the new optional `query` request parameter `order_by`
  - `query` request parameter `ascending` was deprecated
- **2025-10-01** `d9e4ebe71a8a` — 1 info
  - `query` request parameter `agent_ids` was deprecated
- **2025-09-29** `ac8e1eb68404` — 4 warning, 4 info
  - removed the optional property `items/created_by_id` from the response with the `200` status
  - removed the optional property `items/job_type` from the response with the `200` status
  - removed the optional property `items/last_updated_by_id` from the response with the `200` status
  - removed the optional property `items/updated_at` from the response with the `200` status
  - …4 more
- **2025-09-18** `3a2d48137c08` — 3 info
  - added the new optional `query` request parameter `agent_id`
  - added the optional property `items/agent_id` to the response with the `200` status
  - added the optional property `items/background` to the response with the `200` status

[Change history](https://skmtc.dev/yu-code666/apis/letta-api/changes/v1/runs/get.md)

---

[API](https://skmtc.dev/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.dev/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yu-code666/letta-api/revisions/6cec99480c13/schema)