# List org agents > The agents.list operation: GET /api/v1/agents in the REST API and the agents_list tool in the MCP server. Lists the organization's agents, newest first, with their role, scope, live access, limits, tool sets and status. Never returns secrets: an agent's secret is recognised by `secretPrefix`. Filter by `status`; paginate with `limit` (1–100, default 10) and `starting_after`. ## At a glance - **REST:** `GET /api/v1/agents` - **MCP tool:** `agents_list` - **Operation ID:** `agents.list` - **Scope:** Organization - **Permission:** `agents:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Pagination:** `limit` (at most 100) and `starting_after` - **Authentication:** API key with the `agents:read` scope - **Since:** M10 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ------------------------------------ | -------- | ----------- | | `limit` | integer (1 to 100) | No | | | `starting_after` | `agt_…` ID | No | | | `status` | one of `active`, `paused`, `revoked` | No | | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | ------------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | `agt_…` ID | | | `data[].object` | `"agent"` | | | `data[].orgId` | `org_…` ID | | | `data[].name` | string | | | `data[].description` | string or null | | | `data[].contact` | string or null | | | `data[].vendor` | string or null | | | `data[].ownerType` | one of `org`, `app` | | | `data[].appInstallationId` | `ains_…` ID or null | | | `data[].role` | one of `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer` | | | `data[].scope` | object | | | `data[].livemodeAccess` | boolean | | | `data[].limits` | object | | | `data[].limits.rps` | integer or null | | | `data[].limits.mutationsPerDay` | integer or null | | | `data[].limits.amountLimits` | array of object | | | `data[].limits.amountLimits[].operationId` | string | | | `data[].limits.amountLimits[].perCall` | money or null | | | `data[].limits.amountLimits[].perDay` | money or null | | | `data[].toolSets` | array of string | | | `data[].status` | one of `active`, `paused`, `revoked` | | | `data[].clientId` | `ocl_…` ID | | | `data[].authMethod` | one of `client_secret_basic`, `client_secret_post`, `private_key_jwt` | | | `data[].secretPrefix` | string or null | | | `data[].dpopBoundAccessTokens` | boolean | | | `data[].scopes` | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) | | | `data[].createdBy` | string | | | `data[].createdAt` | string | | | `data[].updatedAt` | string | | | `data[].pausedAt` | string or null | | | `data[].revokedAt` | string or null | | | `has_more` | boolean | | | `next_cursor` | `agt_…` ID or null | | ## Examples ### Active agents ```http GET /api/v1/agents?status=active Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "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 } ], "has_more": false, "next_cursor": null } ``` ### One agent per page ```http GET /api/v1/agents?limit=1 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "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 } ], "has_more": true, "next_cursor": "agt_01m4ttwd3veh9apbewxheq5xh8" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | ---------------------------------------- | ------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter or pagination value is invalid. | Fix the fields listed in `details.issues` and send the request again. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#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](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).