---
title: "List agents"
method: GET
path: "/v1/agents"
tags: ["Agents"]
---

# List agents

`GET /v1/agents`

List agents available to your organization.

Agent status reflects whether an agent has ever been published. `published`
agents have a live published version. `draft` agents have not been
published yet.

## Query parameters

- `statuses` ListAgentsStatusFilter[], nullable — Optional status filter. Use `published` to list agents that have a live published version, or `draft` to list agents that have not been published yet. Defaults to `published`.
- `limit` integer
- `next_cursor` string, nullable

## Response `200`

Successful Response

- ListAgentsResponse — Paginated list of agents.
  - `data` Agent[], required — Agents returned for this page.
    - `id` string, uuid, required — Unique ID for the agent.
    - `organization_id` string, uuid, required — Unique ID of the organization that owns the agent.
    - `name` string, required — Display name of the agent.
    - `status` 'draft' | 'published' | 'unknown', required — Current availability status for an agent.
    - `created_at` string, date-time, required — When the agent was created.
    - `description` string, nullable — Short description of the agent, if provided.
  - `pagination` CursorPagination — Cursor-based pagination metadata.
    - `limit` integer — Maximum number of results to return. Default is 10,000, maximum is 50,000.
    - `next_cursor` string, nullable — Token for the next page, if more results are available.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cooper-square-technologies/apis/external-api.md) · [All operations](https://skmtc.net/cooper-square-technologies/apis/external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cooper-square-technologies/external-api/revisions/ab03b3c80494/schema)