List agents

GET /v1/agents

Lists the agents an API key can run, one page at a time.

A personal key lists the agents its owner can run, sorted by updated_at, newest first. This is the same list the agent picker in the Context app shows. A service account key lists every agent in the organization, sorted by created_at, newest first. If the key is limited to specific agents (its Agent scope), the result includes only those. The list never includes archived agents.

The system field is null unless the key is a personal key with agents:write whose owner created the agent. A service account key always gets null.

The key must have the tasks:read capability. For what each capability allows, see Keys.

Query parameters

Name	Type	Required	Default	Description
`limit`	`integer`	No	`20`	The maximum number of agents to return. Must be between 1 and 100. A personal key returns at most 50 agents per page, even when `limit` is higher.
`page`	`string`	No		The `next_page` value from the previous response. Leave it out to get the first page.
`include_archived`	`boolean`	No	`false`	Not supported. Omit it or send `false`. Any other value returns `400`.

Response

Returns 200 with a page of agent objects in data and a next_page value to pass as page. A page can contain fewer agents than limit, or none, and still have a next_page value. Keep requesting pages until next_page is null. For every field, see Agents.

{
  "data": [
    {
      "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
      "archived_at": null,
      "created_at": "2026-10-21T01:35:05.337Z",
      "description": "Answers questions about the sales pipeline",
      "execution_identity": {
        "type": "service_account"
      },
      "mcp_servers": [],
      "metadata": {},
      "model": {
        "id": "default"
      },
      "multiagent": null,
      "name": "Research Assistant",
      "skills": [
        {
          "type": "anthropic",
          "skill_id": "xlsx",
          "version": "latest"
        }
      ],
      "system": null,
      "tools": [
        {
          "type": "agent_toolset_20260401",
          "default_config": {
            "enabled": true,
            "permission_policy": {
              "type": "always_ask"
            }
          },
          "configs": [
            {
              "type": "bash",
              "name": "bash",
              "enabled": true,
              "permission_policy": {
                "type": "always_ask"
              }
            },
            {
              "type": "edit",
              "name": "edit",
              "enabled": true,
              "permission_policy": {
                "type": "always_ask"
              }
            },
            {
              "type": "read",
              "name": "read",
              "enabled": true,
              "permission_policy": {
                "type": "always_allow"
              }
            },
            {
              "type": "write",
              "name": "write",
              "enabled": true,
              "permission_policy": {
                "type": "always_ask"
              }
            },
            {
              "type": "glob",
              "name": "glob",
              "enabled": true,
              "permission_policy": {
                "type": "always_allow"
              }
            },
            {
              "type": "grep",
              "name": "grep",
              "enabled": true,
              "permission_policy": {
                "type": "always_allow"
              }
            },
            {
              "type": "web_fetch",
              "name": "web_fetch",
              "enabled": true,
              "permission_policy": {
                "type": "always_ask"
              },
              "url_sources": null
            },
            {
              "type": "web_search",
              "name": "web_search",
              "enabled": false,
              "permission_policy": {
                "type": "always_ask"
              }
            }
          ]
        }
      ],
      "type": "agent",
      "updated_at": "2026-10-21T01:35:05.337Z",
      "version": 1
    }
  ],
  "next_page": null
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	`limit` is outside 1 to 100. Send a value from 1 to 100.
400	`invalid_request_error`	`page` is not a `next_page` value from this API. Send the `next_page` value from the previous response, unchanged.
400	`invalid_request_error`	`include_archived` is any value other than `false`. Omit it.
400	`invalid_request_error`	The request sends a `created_at[*]` filter (`created_at[gte]` or `created_at[lte]`). Remove it.

Example

curl -sS "$CONTEXT_BASE_URL/v1/agents?limit=20" -H "x-api-key: $CONTEXT_API_KEY"

for agent in client.beta.agents.list(limit=20):  # auto-paginates
    print(agent.id, agent.name)

for await (const agent of client.beta.agents.list({ limit: 20 })) console.log(agent.id, agent.name)