CumulusDocs
Open Studio
On this page

List agents

List agents with their live version, open draft and most recent run. Use the query fields to search, filter and sort.

Operation ID: agents.list.

Request

GET /api/v1/agents

  • TypeScript SDK: client.agents.list (path arguments use path).
  • MCP tool: sdk_client_call with operationId: "agents.list" (path arguments use input.path). Legacy alias: agents_list. Connect to your authenticated /mcp endpoint with an API key for the same environment.
  • Minimum API key role: viewer.
  • Idempotency: No idempotency header required.

Read resource IDs from earlier responses and use a key for the same environment.

Request example

Set each path variable to an ID returned by an earlier API request.

Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Example values are synthetic.

cURL

curl
curl --fail-with-body -sS "${CUMULUS_BASE_URL%/}/api/v1/agents" \
  -H "Authorization: Bearer $CUMULUS_API_KEY"

TypeScript

typescript
import { Cumulus } from "@cumulus/sdk";

const baseUrl = process.env.CUMULUS_BASE_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_BASE_URL and CUMULUS_API_KEY");
const client = new Cumulus({ baseUrl, apiKey });

const response = await client.agents.list({});

Input schema

Path, query and header parameters

cursor

query parameter · Optional.

Type: string. maxLength: 4096.

limit

query parameter · Optional.

Type: integer. At least 1. At most 200. Default: 50.

q

query parameter · Optional.

Type: string. maxLength: 256.

channel

query parameter · Optional.

Type: "cloud" · "phone".

sort

query parameter · Optional.

Type: "updated_desc" · "name_asc". Default: "updated_desc".

JSON request body

This operation has no JSON request body.

Complete OpenAPI schema
OpenAPI JSON
{
  "parameters": [
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "maxLength": 4096
      }
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "default": 50,
        "type": "integer",
        "minimum": 1,
        "maximum": 200
      }
    },
    {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "maxLength": 256,
        "description": "Case-insensitive substring of the agent's name or id; blank matches every agent"
      }
    },
    {
      "name": "channel",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "cloud",
          "phone"
        ],
        "description": "Only agents whose head publication serves this channel"
      }
    },
    {
      "name": "sort",
      "in": "query",
      "required": false,
      "schema": {
        "default": "updated_desc",
        "type": "string",
        "enum": [
          "updated_desc",
          "name_asc"
        ]
      }
    }
  ],
  "requestBody": null
}

Responses

HTTP 200

List agents with their head publication, open draft and last run; search, filter and order server-side

application/json

FieldType or valuesRequiredDescription and limits
agentsarray of objectRequired—
agents[].refobjectRequired—
agents[].ref.tenant_idstring (uuid)Requiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
agents[].ref.kind"agent"Required—
agents[].ref.idstringRequiredminLength: 1. maxLength: 256. pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$.
agents[].namestringRequiredminLength: 1. maxLength: 256.
agents[].headobject or nullRequired—
agents[].head.versionintegerRequired in a non-null parentAt least 0. At most 2147483647.
agents[].head.digeststringRequired in a non-null parentpattern: ^sha256:[a-f0-9]{64}$.
agents[].head.channelsarray of "cloud" · "phone"Required in a non-null parentminItems: 1.
agents[].head.languagesarray of "en" · "es"Required in a non-null parentminItems: 1.
agents[].head.published_atstring (date-time)Required in a non-null parentpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
agents[].draftobject or nullRequired—
agents[].draft.draft_idstring (uuid)Required in a non-null parentIdentifier of the editable draft. Read it from the agent or draft response. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
agents[].draft.revisionintegerRequired in a non-null parentGreater than 0. At most 9007199254740991.
agents[].draft.base_versioninteger or nullRequired in a non-null parentAt least 0. At most 2147483647.
agents[].draft.published_revisioninteger or nullRequired in a non-null parentGreater than 0. At most 9007199254740991.
agents[].created_atstring (date-time)Requiredpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
agents[].updated_atstring (date-time)RequiredThe head's publish time, else created_at: the key of the updated_desc agents.list order pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
agents[].last_runobject or nullRequiredThe most recent non-test run of any version; null when the agent never ran outside Studio tests
agents[].last_run.run_idstring (uuid)Required in a non-null parentRun identifier returned when the run was admitted. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
agents[].last_run.created_atstring (date-time)Required in a non-null parentpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
agents[].last_run.state"admitted" · "running" · "ending" · "completed" · "failed" · "cancelled" · "rejected" · "expired"Required in a non-null parent—
agents[].last_run.dispositionstring or nullRequired in a non-null parent—
issuesarray of objectRequired—
issues[].targetobjectRequired—
issues[].target.owner_idstringRequiredminLength: 1.
issues[].target.environmentstringRequiredminLength: 1.
issues[].target.tenant_idstring (uuid) or nullRequiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
issues[].messagestringRequired—
next_cursorstring or nullRequiredCursor for the next page; null when no next page exists. maxLength: 4096.

Error responses

HTTPDescription
4XXTyped error (ApiError)
5XXTyped error (ApiError)

Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.

Complete OpenAPI schema
OpenAPI JSON
{
  "200": {
    "description": "List agents with their head publication, open draft and last run; search, filter and order server-side",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AgentsListResponse200"
        }
      }
    }
  },
  "4XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "5XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

Referenced schemas

Expand the complete OpenAPI definitions for integrations that generate their own clients.

Complete OpenAPI schema
OpenAPI JSON
{
  "components": {
    "schemas": {
      "AgentsListResponse200": {
        "type": "object",
        "properties": {
          "agents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentSummary"
            }
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "target": {
                  "type": "object",
                  "properties": {
                    "owner_id": {
                      "type": "string",
                      "minLength": 1
                    },
                    "environment": {
                      "type": "string",
                      "minLength": 1
                    },
                    "tenant_id": {
                      "nullable": true,
                      "type": "string",
                      "format": "uuid",
                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
                    }
                  },
                  "required": [
                    "owner_id",
                    "environment",
                    "tenant_id"
                  ],
                  "additionalProperties": false
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "target",
                "message"
              ],
              "additionalProperties": false
            }
          },
          "next_cursor": {
            "nullable": true,
            "type": "string",
            "maxLength": 4096
          }
        },
        "required": [
          "agents",
          "issues",
          "next_cursor"
        ],
        "additionalProperties": false
      },
      "AgentSummary": {
        "type": "object",
        "properties": {
          "ref": {
            "type": "object",
            "properties": {
              "tenant_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "agent"
                ]
              },
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
              }
            },
            "required": [
              "tenant_id",
              "kind",
              "id"
            ],
            "additionalProperties": false
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "head": {
            "nullable": true,
            "type": "object",
            "properties": {
              "version": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2147483647
              },
              "digest": {
                "type": "string",
                "pattern": "^sha256:[a-f0-9]{64}$"
              },
              "channels": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "cloud",
                    "phone"
                  ]
                }
              },
              "languages": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "en",
                    "es"
                  ]
                }
              },
              "published_at": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              }
            },
            "required": [
              "version",
              "digest",
              "channels",
              "languages",
              "published_at"
            ],
            "additionalProperties": false
          },
          "draft": {
            "nullable": true,
            "type": "object",
            "properties": {
              "draft_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
              },
              "revision": {
                "type": "integer",
                "minimum": 0,
                "exclusiveMinimum": true,
                "maximum": 9007199254740991
              },
              "base_version": {
                "nullable": true,
                "type": "integer",
                "minimum": 0,
                "maximum": 2147483647
              },
              "published_revision": {
                "nullable": true,
                "type": "integer",
                "minimum": 0,
                "exclusiveMinimum": true,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "draft_id",
              "revision",
              "base_version",
              "published_revision"
            ],
            "additionalProperties": false
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
            "description": "The head's publish time, else created_at: the key of the updated_desc agents.list order"
          },
          "last_run": {
            "nullable": true,
            "description": "The most recent non-test run of any version; null when the agent never ran outside Studio tests",
            "type": "object",
            "properties": {
              "run_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              },
              "state": {
                "type": "string",
                "enum": [
                  "admitted",
                  "running",
                  "ending",
                  "completed",
                  "failed",
                  "cancelled",
                  "rejected",
                  "expired"
                ]
              },
              "disposition": {
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "run_id",
              "created_at",
              "state",
              "disposition"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "ref",
          "name",
          "head",
          "draft",
          "created_at",
          "updated_at",
          "last_run"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthenticated",
                  "forbidden",
                  "not_found",
                  "conflict",
                  "invalid_request",
                  "idempotency_conflict",
                  "policy_denied",
                  "capability_unavailable",
                  "provider_unavailable",
                  "knowledge_unavailable",
                  "publication_invalid",
                  "run_not_active",
                  "rate_limited",
                  "outcome_unknown",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "none",
                  "unknown"
                ]
              },
              "details": {
                "type": "object",
                "additionalProperties": {}
              }
            },
            "required": [
              "code",
              "message",
              "retryable",
              "outcome"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      }
    }
  }
}

Errors and recovery

See API error handling and Troubleshooting.

Content version c8f74611Customer SDKMarkdown source
List agents · Cumulus developer docs