Get an agent

GET /v1/agents/{agent_id}

Returns an agent that the calling API key can run.

A key can read only the agents in its Agent scope, if it has one. An agent ID that does not exist returns 403, not 404: the same response as for an agent outside the key’s Agent scope.

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

Path parameters

Name	Type	Required	Default	Description
agent_id	string	Yes		The ID of the agent to return.

Query parameters

Name	Type	Required	Default	Description
version	integer	No		Not supported. Omit it or send 1. Any other value returns 400. Every agent has exactly one version.

Response

Returns 200 with the agent object. For every field, see Agents.

{
  "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
}

Errors

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

Status	error.type	Cause and fix
400	invalid_request_error	version is not 1. Omit version or send 1.
403	permission_error	The key is not allowed to run this agent, or no agent has this ID. Check the agent ID and the key’s Agent scope.

Example

cURL

curl -sS "$CONTEXT_BASE_URL/v1/agents/6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60" -H "x-api-key: $CONTEXT_API_KEY"

Python

agent = client.beta.agents.retrieve("6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60")

TypeScript

const agent = await client.beta.agents.retrieve("6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60")