---
title: "List agents"
url: https://hexelstudio.com/docs/api/registry/agents/list
---

# List agents

**GET** `/registry/v1/agents`

List agents with optional filters

## Query parameters

- `author: optional string`

  Filter by author

- `status: optional string`

  Filter by status

- `limit: optional integer`

  Limit

  Default: `20`

- `offset: optional integer`

  Offset

  Default: `0`

## Returns

`200` OK (`AgentsListResponse`)

- `agents: optional array of Agent`

  - `allowed_org_ids: optional array of string`

  - `author: optional string`

  - `capabilities: optional array of string`

  - `created_at: optional string`

  - `description: optional string`

  - `endpoint: optional string`

  - `id: optional string`

  - `image: optional string`

  - `image_pull_secret: optional ImagePullSecret`

    - `password: optional string`

    - `registry: optional string`

    - `username: optional string`

  - `manifest: optional AgentManifest`

    - `authentication: optional object`

    - `capabilities: optional object`

    - `description: optional string`

    - `input_schema: optional object`

    - `name: optional string`

    - `output_schema: optional object`

    - `runtime: optional object`

    - `skills: optional array of ManifestSkill`

      - `id: optional string`

      - `inputModes: optional array of string`

      - `outputModes: optional array of string`

    - `url: optional string`

    - `version: optional string`

  - `metadata: optional map[string]`

  - `name: optional string`

  - `org_id: optional string`

  - `public_key: optional string`

  - `state: optional string`

    registered, deploying, running, active, idle, sleeping, stopped, failed

  - `updated_at: optional string`

  - `version: optional string`

  - `visibility: optional string`

    private, public

- `total: optional integer`

## Errors

- `500` Internal Server Error

## Example

```bash
curl --request GET \
  --url 'https://compute.hexelstudio.com/registry/v1/agents'
```

### Response (200)

```json
{
  "agents": [
    {
      "allowed_org_ids": [
        "string"
      ],
      "author": "string",
      "capabilities": [
        "string"
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "description": "string",
      "endpoint": "string",
      "id": "string",
      "image": "string",
      "image_pull_secret": {
        "password": "string",
        "registry": "string",
        "username": "string"
      },
      "manifest": {
        "authentication": {},
        "capabilities": {},
        "description": "string",
        "input_schema": {},
        "name": "string",
        "output_schema": {},
        "runtime": {},
        "skills": [
          {
            "id": "string",
            "inputModes": [
              "string"
            ],
            "outputModes": [
              "string"
            ]
          }
        ],
        "url": "string",
        "version": "string"
      },
      "metadata": {
        "key": "string"
      },
      "name": "string",
      "org_id": "string",
      "public_key": "string",
      "state": "string",
      "updated_at": "2026-01-01T00:00:00Z",
      "version": "string",
      "visibility": "string"
    }
  ],
  "total": 0
}
```

### Response (500)

```json
{
  "error": "string",
  "message": "string"
}
```