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

# GET /api/v1/agents

`GET /api/v1/agents`

Retrieves multiple agents.

## Query parameters

- `joins` union
  - string[]
  - 'squads'
- `pageNumber` number — The page number.
- `pageSize` number — The page size.
- `referenceIds` union
  - string[]
  - string, uuid — A UUID v4 string that identifies an entity.
- `search` string — Search term to filter agents by name, internal name, role, or prompt.
- `squadIds` union
  - string[]
  - string, uuid — A UUID v4 string that identifies an entity.
- `versionIds` union
  - string[]
  - string, uuid — A UUID v4 string that identifies an entity.

## Headers

- `authorization` string, required — The API key to use for authentication. Can be created in the api keys section on the workspace settings page.

## Response `200`

Retrieves all agents for the workspace.

- union[]
  - union
    - object
      - `createdAt` string, date-time, required
      - `id` string, uuid, required — A UUID v4 string that identifies an entity.
      - `isRemoved` boolean, required
      - `referenceId` string, uuid, nullable, required — The ID of the original entity in production.
      - `updatedAt` string, date-time, required
      - `versionId` string, uuid, required — A UUID v4 string that identifies an entity.
      - `codeRuntime` boolean, required — Whether the agent should be able to execute JavaScript code using the Code Runtime tool.
      - `internalName` string, nullable, required — The internal name of the agent. For internal use only.
      - `iterations` number, required — The number of iterations (steps) the agent can execute in a single execution.
      - `llm` 'claude-haiku-4-5' | 'claude-opus-4-8' | 'claude-opus-4-6' | 'claude-opus-4-5' | 'claude-sonnet-4-6' | 'claude-sonnet-4-5' | 'gpt-5.2' | 'gpt-5.5' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'gemini-3.5-flash' | 'gemini-3-flash' | 'gemini-3-pro' | 'gemini-3.1-pro' | 'kimi-k2.5' | 'kimi-k2.6' | 'grok-4.3' | 'grok-4.5', required — The LLM model key to use for the agent.
      - `llmProviderId` string, uuid, nullable, required — The id of the LLM provider to use for the agent.
      - `name` string, required — The name of the agent.
      - `picture` string, nullable, required — The picture of the agent.
      - `planning` boolean, required — Whether the agent should plan before each execution.
      - `prompt` string, required — The main description of the agent's behavior.
      - `reasoningMode` 'low' | 'medium' | 'high' | 'xhigh' | 'null', nullable, required — The reasoning mode to use for the agent. If null, reasoning will be disabled.
      - `role` string, required — The role of the agent. Particularly useful to give other agents context of what the agent does.
      - `superIdentityId` string, uuid, required — The super identity ID associated with the agent.
      - `temperature` number, required — The temperature to use for the agent. The lower the more deterministic. The higher the more creative.
      - `timezone` 'Africa/Cairo' | 'Africa/Johannesburg' | 'America/Chicago' | 'America/Denver' | 'America/Los_Angeles' | 'America/New_York' | 'America/Sao_Paulo' | 'America/Manaus' | 'Asia/Dubai' | 'Asia/Kolkata' | 'Asia/Shanghai' | 'Asia/Singapore' | 'Asia/Tokyo' | 'Australia/Sydney' | 'Europe/Berlin' | 'Europe/London' | 'Europe/Moscow' | 'Europe/Paris' | 'Pacific/Auckland' | 'Pacific/Auckland2' | 'UTC' | 'auto' | 'null', nullable, required — The timezone to use for the agent. If null, no timezone will be used.
      - `toolCount` integer, required — The number of tools currently associated with the agent.
      - `voiceId` string, uuid, nullable, required — The TTS voice to use for audio responses. Null when disabled for the agent.
      - `workspaceId` string, uuid, required — The workspace ID that owns the agent.
      - `squadAgents` object[], required
        - `createdAt` string, date-time, required
        - `updatedAt` string, date-time, required
        - `agentId` string, uuid, required — A UUID v4 string that identifies an entity.
        - `squadId` string, uuid, required — A UUID v4 string that identifies an entity.
        - `type` 'member' | 'main', required
        - `squad` object, required
          - `createdAt` string, date-time, required
          - `id` string, uuid, required — A UUID v4 string that identifies an entity.
          - `isRemoved` boolean, required
          - `referenceId` string, uuid, nullable, required — The ID of the original entity in production.
          - `updatedAt` string, date-time, required
          - `versionId` string, uuid, required — A UUID v4 string that identifies an entity.
          - `description` string, nullable, required — The internal description of the squad.
          - `mode` 'hierarchical' | 'flat', required — The management mode. In flat, agents redirect the chat to one another. In hierarchical, all iterations are intermediated by the manager.
          - `name` string, required — The display name of the squad.
          - `picture` string, nullable, required — The picture associated with the squad.
          - `superIdentityId` string, uuid, required — The super identity ID associated with the squad.
          - `workspaceId` string, uuid, required — The workspace ID that owns the squad.
    - object
      - `createdAt` string, date-time, required
      - `id` string, uuid, required — A UUID v4 string that identifies an entity.
      - `isRemoved` boolean, required
      - `referenceId` string, uuid, nullable, required — The ID of the original entity in production.
      - `updatedAt` string, date-time, required
      - `versionId` string, uuid, required — A UUID v4 string that identifies an entity.
      - `codeRuntime` boolean, required — Whether the agent should be able to execute JavaScript code using the Code Runtime tool.
      - `internalName` string, nullable, required — The internal name of the agent. For internal use only.
      - `iterations` number, required — The number of iterations (steps) the agent can execute in a single execution.
      - `llm` 'claude-haiku-4-5' | 'claude-opus-4-8' | 'claude-opus-4-6' | 'claude-opus-4-5' | 'claude-sonnet-4-6' | 'claude-sonnet-4-5' | 'gpt-5.2' | 'gpt-5.5' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gemini-2.5-flash' | 'gemini-2.5-pro' | 'gemini-3.5-flash' | 'gemini-3-flash' | 'gemini-3-pro' | 'gemini-3.1-pro' | 'kimi-k2.5' | 'kimi-k2.6' | 'grok-4.3' | 'grok-4.5', required — The LLM model key to use for the agent.
      - `llmProviderId` string, uuid, nullable, required — The id of the LLM provider to use for the agent.
      - `name` string, required — The name of the agent.
      - `picture` string, nullable, required — The picture of the agent.
      - `planning` boolean, required — Whether the agent should plan before each execution.
      - `prompt` string, required — The main description of the agent's behavior.
      - `reasoningMode` 'low' | 'medium' | 'high' | 'xhigh' | 'null', nullable, required — The reasoning mode to use for the agent. If null, reasoning will be disabled.
      - `role` string, required — The role of the agent. Particularly useful to give other agents context of what the agent does.
      - `superIdentityId` string, uuid, required — The super identity ID associated with the agent.
      - `temperature` number, required — The temperature to use for the agent. The lower the more deterministic. The higher the more creative.
      - `timezone` 'Africa/Cairo' | 'Africa/Johannesburg' | 'America/Chicago' | 'America/Denver' | 'America/Los_Angeles' | 'America/New_York' | 'America/Sao_Paulo' | 'America/Manaus' | 'Asia/Dubai' | 'Asia/Kolkata' | 'Asia/Shanghai' | 'Asia/Singapore' | 'Asia/Tokyo' | 'Australia/Sydney' | 'Europe/Berlin' | 'Europe/London' | 'Europe/Moscow' | 'Europe/Paris' | 'Pacific/Auckland' | 'Pacific/Auckland2' | 'UTC' | 'auto' | 'null', nullable, required — The timezone to use for the agent. If null, no timezone will be used.
      - `toolCount` integer, required — The number of tools currently associated with the agent.
      - `voiceId` string, uuid, nullable, required — The TTS voice to use for audio responses. Null when disabled for the agent.
      - `workspaceId` string, uuid, required — The workspace ID that owns the agent.

## Other responses

- `401` — Unauthorized.

---

[API](https://skmtc.dev/zaia/apis/public-api.md) · [All operations](https://skmtc.dev/zaia/apis/public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zaia/public-api/revisions/58da3b2ba49f/schema)