Documentation menu
Agents

List agents

GET /api/v1/agents

List agents owned by the authenticated organization. Specify projectId for a single Project. Sessions must specify organizationId when listing Agents across Projects. Organization-scoped credentials may omit both.

Query Parameters

  • filter: Filter by Agent name or slug (partial match, case-insensitive)
  • limit: Maximum results (default 20)
  • cursor: Opaque cursor returned in pagination.nextCursor.

Parameters

query

NameTypeRequiredDescription
filterstringoptionalFilters agents using the server-side agent search expression. Applies to List agents.
projectIdstringoptionalFilters results to the specified Project. Applies to List agents.
organizationIdstringoptionalSelects the organization for the Agent list. Required for sessions when projectId is omitted. Omit when selecting a single Project.
limitintegeroptionalSets the maximum number of resources returned in this page. Applies to List agents.
cursorstringoptionalOpaque cursor returned by the previous page; omit it to read the first page. Applies to List agents.

Responses

StatusDescriptionBody
200Response for status 200application/json — object — agents: array<one of 2 types> (required); pagination: object (required)
400The request is malformed or cannot be processed.application/json — PublicApiError — error: object (required)
401Authentication failed. The Authorization header is missing, or the credential is invalid or expired.application/json — PublicApiError — error: object (required)
403Access denied. The authenticated user does not have permission to perform this action.application/json — PublicApiError — error: object (required)
404Resource not found.application/json — PublicApiError — error: object (required)
409Request conflicts with current state of the resource, including safe deployment conflict classifications.application/json — PublicApiError — error: object (required)
422Request validation failed. Check the request body, query parameters, or path parameters.application/json — PublicApiError — error: object (required)
429Too many requests.application/json — PublicApiError — error: object (required)
500The server could not complete the request.application/json — PublicApiError — error: object (required)
503Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff.application/json — PublicApiError — error: object (required)