Skip to content
Docs
APISign inStart free

List org agents

The agents.list operation: GET /api/v1/agents in the REST API and the agents_list tool in the MCP server.

GET/api/v1/agents

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

FieldTypeRequiredDescription
limitinteger (1 to 100)No
starting_afteragt_… IDNo
statusone of active, paused, revokedNo

Response

200 OK with a JSON object, a page of the list (newest first):

FieldTypeDescription
object"list"
dataarray of object
data[].idagt_… ID
data[].object"agent"
data[].orgIdorg_… ID
data[].namestring
data[].descriptionstring or null
data[].contactstring or null
data[].vendorstring or null
data[].ownerTypeone of org, app
data[].appInstallationIdains_… ID or null
data[].roleone of org_admin, billing_admin, finance, tax_manager, support, developer, viewer
data[].scopeobject
data[].livemodeAccessboolean
data[].limitsobject
data[].limits.rpsinteger or null
data[].limits.mutationsPerDayinteger or null
data[].limits.amountLimitsarray of object
data[].limits.amountLimits[].operationIdstring
data[].limits.amountLimits[].perCallmoney or null
data[].limits.amountLimits[].perDaymoney or null
data[].toolSetsarray of string
data[].statusone of active, paused, revoked
data[].clientIdocl_… ID
data[].authMethodone of client_secret_basic, client_secret_post, private_key_jwt
data[].secretPrefixstring or null
data[].dpopBoundAccessTokensboolean
data[].scopesarray of one of 84 values, e.g. org:read, org:write, org:admin (all in the OpenAPI document)
data[].createdBystring
data[].createdAtstring
data[].updatedAtstring
data[].pausedAtstring or null
data[].revokedAtstring or null
has_moreboolean
next_cursoragt_… 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

CodeHTTP statusWhenWhat to do
validation_failed400A filter or pagination value is invalid.Fix the fields listed in details.issues and send the request again.
permission_denied403You 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: api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.