> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Agents

> Get a paginated list of all agents.

Get a paginated list of all agents.

### Query parameters

<ParamField query="page" type="integer">
  Page number
</ParamField>

<ParamField query="page_size" type="integer">
  Items per page
</ParamField>

<ParamField query="status" type="string,null">
  Filter by status
</ParamField>

### Response

`AgentListResponse-Input`

<ResponseField name="request_id" type="string,null">
  Request tracking ID
</ResponseField>

<ResponseField name="timestamp" type="string (date-time)">
  Response timestamp
</ResponseField>

<ResponseField name="total" type="integer" required>
  Total number of items
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="page_size" type="integer">
  Items per page
</ResponseField>

<ResponseField name="has_next" type="boolean">
  Whether there are more pages
</ResponseField>

<ResponseField name="has_prev" type="boolean">
  Whether there are previous pages
</ResponseField>

<ResponseField name="items" type="AgentDetailResponse[]">
  List of agents

  <Expandable title="AgentDetailResponse">
    <ResponseField name="agent_id" type="string" required>
      Agent identifier
    </ResponseField>

    <ResponseField name="model_name" type="string" required>
      Model name
    </ResponseField>

    <ResponseField name="created_at" type="string (date-time)" required>
      Creation timestamp
    </ResponseField>

    <ResponseField name="conversation_count" type="integer">
      Number of conversations
    </ResponseField>

    <ResponseField name="total_tokens_used" type="integer">
      Total tokens used
    </ResponseField>

    <ResponseField name="config" type="object">
      Agent configuration
    </ResponseField>

    <ResponseField name="status" type="string">
      Agent status
    </ResponseField>
  </Expandable>
</ResponseField>

### Status codes

| Code | Meaning |
| - | - |
| `200` | List of agents |
| `401` | Authentication required |
| `422` | Validation Error |
| `429` | Rate limit exceeded |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'http://localhost:8000/agents' \
    --header "Authorization: Bearer $STATESET_AGENTS_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2026-08-31T14:22:05Z",
    "total": 102,
    "page": 1,
    "page_size": 20,
    "has_next": false,
    "has_prev": false,
    "items": [
      {
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "model_name": "string",
        "created_at": "2026-08-31T14:22:05Z",
        "conversation_count": 0,
        "total_tokens_used": 0,
        "config": {},
        "status": "active"
      }
    ]
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.