---
title: "List agent entities, cursor-paginated."
method: GET
path: "/v1/agents/pages"
tags: ["beta.agents"]
---

# List agent entities, cursor-paginated.

`GET /v1/agents/pages`

Retrieve a page of agent entities. Unlike the deprecated `GET /v1/agents`, this endpoint paginates by opaque cursor and honors per-agent sharing, returning only agents the caller is authorized to see.

## Query parameters

- `page_size` integer — Number of agents per page
- `deployment_chat` boolean, nullable
- `sources` RequestSource[], nullable
- `name` string, nullable — Filter by agent name
- `search` string, nullable — Search agents by name or ID
- `id` string, nullable
- `page_token` string, nullable — Opaque cursor from a previous response's next_page_token. When set, results page forward from the cursor.

## Response `200`

Successful Response

- AgentListPage
  - `object` 'list'
  - `data` Agent[], required
    - `instructions` string, nullable — Instruction prompt the model will follow during the conversation.
    - `tools` union[] — List of tools which are available to the model during the conversation.
      - union
        - FunctionTool
          - `type` 'function'
          - `function` Function, required
            - `name` string, required
            - `description` string
            - `strict` boolean
            - `parameters` object, required
        - WebSearchTool
          - `tool_configuration` ToolConfiguration
            - `exclude` string[], nullable
            - `include` string[], nullable
            - `requires_confirmation` string[], nullable
          - `type` 'web_search'
        - WebSearchPremiumTool
          - `tool_configuration` ToolConfiguration
            - `exclude` string[], nullable
            - `include` string[], nullable
            - `requires_confirmation` string[], nullable
          - `type` 'web_search_premium'
        - CodeInterpreterTool
          - `tool_configuration` ToolConfiguration
            - `exclude` string[], nullable
            - `include` string[], nullable
            - `requires_confirmation` string[], nullable
          - `type` 'code_interpreter'
        - ImageGenerationTool
          - `tool_configuration` ToolConfiguration
            - `exclude` string[], nullable
            - `include` string[], nullable
            - `requires_confirmation` string[], nullable
          - `type` 'image_generation'
        - DocumentLibraryTool
          - `tool_configuration` ToolConfiguration
            - `exclude` string[], nullable
            - `include` string[], nullable
            - `requires_confirmation` string[], nullable
          - `type` 'document_library'
          - `library_ids` string[], required — Ids of the library in which to search.
        - CustomConnector
          - `type` 'connector'
          - `connector_id` string, required
          - `authorization` union
            - OAuth2TokenAuth
              - …
            - APIKeyAuth
              - …
          - `tool_configuration` ToolConfiguration
            - `exclude` string[], nullable
            - `include` string[], nullable
            - `requires_confirmation` string[], nullable
    - `completion_args` CompletionArgs — White-listed arguments from the completion API
      - `stop` union
        - string
        - string[]
      - `presence_penalty` number, nullable
      - `frequency_penalty` number, nullable
      - `temperature` number, nullable
      - `top_p` number, nullable
      - `max_tokens` integer, nullable
      - `random_seed` integer, nullable
      - `prediction` Prediction — Enable users to specify an expected completion, optimizing response times by leveraging known or predictable content.
        - `type` 'content'
        - `content` string
      - `response_format` ResponseFormat — Specify the format that the model must output. By default it will use `{ "type": "text" }`. Setting to `{ "type": "json_object" }` enables JSON mode, which guarantees the message the model generates is in JSON. When using JSON mode you MUST also instruct the model to produce JSON yourself with a system or a user message. Setting to `{ "type": "json_schema" }` enables JSON schema mode, which guarantees the message the model generates is in JSON and follows the schema you provide.
        - `type` 'text' | 'json_object' | 'json_schema'
        - `json_schema` JsonSchema
          - `name` string, required
          - `description` string, nullable
          - `schema` object, required
          - `strict` boolean
      - `tool_choice` 'auto' | 'none' | 'any' | 'required'
      - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
    - `guardrails` GuardrailConfig[], nullable
      - `block_on_error` boolean — If true, return HTTP 403 and block request in the event of a server-side error
      - `moderation_llm_v1` ModerationLLMV1Config
        - `model_name` string — Override model name. Should be omitted in general.
        - `custom_category_thresholds` ModerationLLMV1CategoryThresholds
          - `sexual` number, nullable
          - `hate_and_discrimination` number, nullable
          - `violence_and_threats` number, nullable
          - `dangerous_and_criminal_content` number, nullable
          - `selfharm` number, nullable
          - `health` number, nullable
          - `financial` number, nullable
          - `law` number, nullable
          - `pii` number, nullable
        - `ignore_other_categories` boolean — If true, only evaluate categories in custom_category_thresholds; others are ignored.
        - `action` 'none' | 'block'
      - `moderation_llm_v2` ModerationLLMV2Config
        - `model_name` string — Override model name. Should be omitted in general.
        - `custom_category_thresholds` ModerationLLMV2CategoryThresholds
          - `sexual` number, nullable
          - `hate_and_discrimination` number, nullable
          - `violence_and_threats` number, nullable
          - `dangerous` number, nullable
          - `criminal` number, nullable
          - `selfharm` number, nullable
          - `health` number, nullable
          - `financial` number, nullable
          - `law` number, nullable
          - `pii` number, nullable
          - `jailbreaking` number, nullable
        - `ignore_other_categories` boolean — If true, only evaluate categories in custom_category_thresholds; others are ignored.
        - `action` 'none' | 'block'
    - `model` string, required
    - `name` string, required
    - `description` string, nullable
    - `handoffs` string[], nullable
    - `metadata` MetadataDict — Custom type for metadata with embedded validation.
    - `object` 'agent'
    - `id` string, required
    - `version` integer, required
    - `versions` integer[], required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `deployment_chat` boolean, required
    - `source` string, required
    - `version_message` string, nullable
  - `next_page_token` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/mistral/apis/mistral-ai-api.md) · [All operations](https://skmtc.net/mistral/apis/mistral-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mistral/mistral-ai-api/versions/933c4ebdcd72/schema)