Get an org agent
The agents.get operation: GET /api/v1/agents/{id} in the REST API and the agents_get tool in the MCP server.
GET
/api/v1/agents/{id}Returns one agent: role and scope, live access, token scopes, limits, tool sets, status and its OAuth clientId. Never the secret.
At a glance
- REST:
GET /api/v1/agents/{id} - MCP tool:
agents_get - Operation ID:
agents.get - Scope: Organization
- Permission:
agents:read - Risk tier:
read - Dry run: Not supported
- Idempotency: Not needed (read only)
- Modes: Test and live
- Authentication: API key with the
agents:readscope - Since: M10
Request
Path parameters
| Field | Type | Description |
|---|---|---|
id | agt_… ID |
Query parameters
This operation takes no query parameters.
Response
200 OK with a JSON object:
| Field | Type | Description |
|---|---|---|
id | agt_… ID | |
object | "agent" | |
orgId | org_… ID | |
name | string | |
description | string or null | |
contact | string or null | |
vendor | string or null | |
ownerType | one of org, app | |
appInstallationId | ains_… ID or null | |
role | one of org_admin, billing_admin, finance, tax_manager, support, developer, viewer | |
scope | object | |
livemodeAccess | boolean | |
limits | object | |
limits.rps | integer or null | |
limits.mutationsPerDay | integer or null | |
limits.amountLimits | array of object | |
limits.amountLimits[].operationId | string | |
limits.amountLimits[].perCall | money or null | |
limits.amountLimits[].perDay | money or null | |
toolSets | array of string | |
status | one of active, paused, revoked | |
clientId | ocl_… ID | |
authMethod | one of client_secret_basic, client_secret_post, private_key_jwt | |
secretPrefix | string or null | |
dpopBoundAccessTokens | boolean | |
scopes | array of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document) | |
createdBy | string | |
createdAt | string | |
updatedAt | string | |
pausedAt | string or null | |
revokedAt | string or null |
Examples
An agent
HTTP
GET /api/v1/agents/agt_01m4ttwd3veh9apbewxheq5xh8
Authorization: Bearer or_test_…
Response (200):
JSON
{
"id": "agt_01m4ttwd3veh9apbewxheq5xh8",
"object": "agent",
"orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
"name": "Bookkeeper",
"description": "Prepares and files the quarterly OSS return",
"contact": "ops@acme.example",
"vendor": "In-house, Claude via the MCP server",
"ownerType": "org",
"appInstallationId": null,
"role": "finance",
"scope": {
"type": "org"
},
"livemodeAccess": false,
"limits": {
"rps": null,
"mutationsPerDay": null,
"amountLimits": [
{
"operationId": "refunds.create",
"perCall": null,
"perDay": {
"amount": "200000000",
"currency": "EUR"
}
}
]
},
"toolSets": [],
"status": "active",
"clientId": "ocl_01m4ttwd3veh9apbewxheq5xh9",
"authMethod": "client_secret_basic",
"secretPrefix": "or_cs_Exampl",
"dpopBoundAccessTokens": false,
"scopes": ["filings:read", "filings:write", "tasks:read", "tasks:write"],
"createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
"createdAt": "2026-10-25T09:00:00.000Z",
"updatedAt": "2026-10-25T09:00:00.000Z",
"pausedAt": null,
"revokedAt": null
}
Errors
| Code | HTTP status | When | What to do |
|---|---|---|---|
resource_not_found | 404 | No agent with this ID exists in the organization. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
permission_denied | 403 | You can't see the organization's agents. | Ask an organization owner or admin for a role or scope that allows this action. |
It can also return these common errors: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.