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

# List Agents

`GET /agents`

List available agents with filtering and pagination.

## Query parameters

- `page` integer
- `page_size` integer
- `category` string, nullable

## Headers

- `Authorization` string, required

## Response `200`

Successful Response

- AgentListResult — Result of listing agents with optional filtering and pagination.
  - `agents` AgentMetadata[], required — Agents for the current page
    - `id` string, required — Stable agent ID (ag_<nanoid>) used for API routing
    - `description` string, nullable — Agent description
    - `labs` boolean — Whether this agent is in labs
    - `input_schema` object, nullable — Input JSON schema
    - `name` string, required — Agent name
    - `output_schema` object, nullable — Output JSON schema
    - `categories` string[] — Category IDs for discovery and filtering
    - `ui` AgentUIMetadata — UI presentation metadata for an agent.
      - `title` string, nullable — Display name override
      - `description` string, nullable — Description override for UI
      - `icon` string — Lucide icon key (e.g. 'spell-check')
  - `total` integer, required — Total number of agents matching filters
  - `page` integer, required — Current page number (1-based)
  - `page_size` integer, required — Number of items per page
  - `total_pages` integer, required — Total number of pages

## Other responses

- `401` — Authentication failed or no valid API key provided.
- `403` — Forbidden
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/markup/apis/api-reference.md) · [All operations](https://skmtc.net/markup/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/markup/api-reference/revisions/8e28e770c55d/schema)