---
title: "List agents (cursor-paginated; ?search=)"
method: GET
path: "/agents"
tags: ["Agents"]
---

# List agents (cursor-paginated; ?search=)

`GET /agents`

## Query parameters

- `cursor` string
- `limit` integer
- `search` string

## Response `200`

A page of agents in the canonical list envelope.

- object — The canonical v2 list envelope. Every list endpoint returns this shape; per-endpoint `items` element types (and documented extras like `total`) are declared on each operation.
  - `object` 'list', required
  - `items` Agent[], required — The page of objects. Element type is per-endpoint.
    - `object` 'agent', required
    - `id` string, uuid, required
    - `name` string, required
    - `workspaceId` string, uuid, required
    - `createdAt` string, date-time, required
    - `apiKeyOwned` boolean, required — True iff this agent's `chat_session` row has a non-null `created_by_api_key_id` — i.e. it was created by the API and is owned by the caller's org. Always `true` on v2 read paths today; surfaced for forward compatibility.
    - `lastRun` RunSummary, required
      - `object` 'run', required
      - `id` string, required
      - `agentId` string, uuid, required
      - `status` 'running' | 'completed' | 'needs_input' | 'step_cap_hit' | 'incomplete' | 'cancelled' | 'errored' | 'timed_out', required — Single discriminator for the run's lifecycle. `needs_input` means the run completed cleanly but the agent's last assistant message included an `ask-questions` tool call; answer by sending a follow-up run on the same agent. `incomplete` means the model finished the step but the AI SDK could not parse a tool call it tried to emit (or it hit the output-token cap mid-tool-call), so the multi-step loop ended without the work being done — recoverable by sending a follow-up run on the same agent. Deploy restarts are auto-followed server-side, so callers never observe a `superseded` value.
      - `prompt` string, required — The user prompt that drove this run, truncated to 200 characters with an ellipsis when longer. Suitable for a run-history list item; for the full prompt use Get Run.
      - `model` 'origami-lite' | 'origami-max', required — Public model id the run actually executed on. When the run has no assistant message yet (still admitting), falls back to the plan default.
      - `steps` RunSteps, required — Agent step progress. `completed` is the number of multi-step loop iterations the agent has actually executed; `max` is the plan-determined hard cap. Once `completed === max`, the run's `status` becomes `step_cap_hit`.
        - `completed` integer, required
        - `max` integer, required
      - `startedAt` string, date-time, required
      - `completedAt` string, date-time, nullable
  - `nextCursor` string, nullable, required — Cursor for the next page; `null` means this is the last page.
  - `url` string, required — The path this list was fetched from (query string excluded).

## Other responses

- `401` — Missing or invalid API key

---

[API](https://skmtc.net/origami/apis/origami-agent-api.md) · [All operations](https://skmtc.net/origami/apis/origami-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/origami/origami-agent-api/revisions/8083ad7fe081/schema)