> ## Documentation Index > Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt > Use this file to discover all available pages before exploring further. # List agents > List returns agent tasks (one level deep). The account field controls scoping: "" = caller only, "*" = all accounts, "joe" = a specific account. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agents openapi: 3.0.0 info: title: Murmur REST API description: >- PRE-ALPHA: INTERFACE SUBJECT TO CHANGE WITHOUT NOTICE. The murmur REST API lets you spawn agents, track their progress, manage their task lists, and read and write catalog resources from any HTTP client. version: v1 servers: - url: https://api.murmur.dev security: - ApiKey: [] tags: - name: MurmurService paths: /v1/agents: post: tags: - MurmurService summary: List agents description: >- List returns agent tasks (one level deep). The account field controls scoping: "" = caller only, "*" = all accounts, "joe" = a specific account. operationId: MurmurService_List requestBody: content: application/json: schema: $ref: '#/components/schemas/v1ListRequest' required: true responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v1ListResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' components: schemas: v1ListRequest: type: object properties: parentId: $ref: '#/components/schemas/v1AgentId' account: type: string description: |- account scope — the ONLY control over which accounts are listed: "" = caller's own agents (default), "*" = every account, "joe" = one account under the caller's own provider, "service_profile/deploy" = one account under an explicit owner provider (the only way to scope across providers — a bare name always resolves under the caller's). includeTerminal: type: boolean description: >- Also include terminal (completed/failed/canceled) agents. This widens the phase filter only; it does NOT change the account scope (see `account`). tenant: $ref: '#/components/schemas/v1Tenant' v1ListResponse: type: object properties: entries: type: array items: $ref: '#/components/schemas/v1ListEntry' googleRpcStatus: type: object properties: code: type: integer format: int32 description: >- Numeric status code for the failure, matching the HTTP status of the response via the standard mapping (e.g. 3 INVALID_ARGUMENT → 400, 5 NOT_FOUND → 404, 7 PERMISSION_DENIED → 403, 16 UNAUTHENTICATED → 401). message: type: string description: Human-readable description of what caused the failure. details: type: array items: $ref: '#/components/schemas/protobufAny' description: >- Machine-readable error details, when the failure carries them. Usually empty. description: The error envelope returned on every non-2xx response. v1AgentId: type: object properties: tenant: $ref: '#/components/schemas/v1Tenant' ownerProvider: $ref: '#/components/schemas/v1Provider' account: type: string description: >- Owner account: username for identity-provider owners, service-profile name for PROVIDER_SERVICE_PROFILE. agent: type: array items: type: string title: |- Agent path — the hierarchy from root to leaf. Root agent: ["fix-bug"] Child: ["fix-bug", "api"] Grandchild: ["fix-bug", "api", "tests"] workspace: type: string description: >- Workspace this agent belongs to; scopes its repos, environment, and base branches. Optional at spawn: when empty, the server selects one, so a returned AgentId always carries a concrete workspace. description: >- Identifies an agent. The identity is (tenant, workspace, owner, agent path); the workspace scopes the agent's repos, environment, and base branches. v1Tenant: type: object properties: provider: $ref: '#/components/schemas/v1Provider' org: type: string title: username or org name description: |- Tenant identifies an organization within a provider. It is the unit of multi-tenant scoping — all resources (agents, pools, VMs) belong to exactly one tenant. v1ListEntry: type: object properties: agentId: $ref: '#/components/schemas/v1AgentId' phase: $ref: '#/components/schemas/v1Phase' cost: type: number format: double progressAt: type: string format: date-time repos: type: array items: type: string title: '"org/repo" names' dashboardUrl: type: string description: >- Dashboard URL for the agent. Empty when the server has no public URL configured. inputTokens: type: string format: int64 description: >- Cumulative token usage. Unified, disjoint partition; total_tokens is the server-derived sum (input + cached + output) so clients never re-derive it. cachedInputTokens: type: string format: int64 outputTokens: type: string format: int64 totalTokens: type: string format: int64 needsInput: type: string description: >- The agent's "needs input" prompt: non-empty when it is blocked awaiting a human decision or answer, empty otherwise. protobufAny: type: object properties: '@type': type: string description: >- Identifies the payload type of this detail value; the remaining properties are that type's fields. additionalProperties: {} description: >- A structured detail value. `@type` identifies the payload type; the remaining properties are that type's fields. v1Provider: type: string enum: - PROVIDER_UNSPECIFIED - PROVIDER_GITHUB_OAUTH - PROVIDER_GITHUB_APP - PROVIDER_GOOGLE_OIDC - PROVIDER_SERVICE_PROFILE default: PROVIDER_UNSPECIFIED description: |- Provider identifies the identity provider type for a tenant namespace. Each provider is a distinct namespace — no cross-provider mixing. - PROVIDER_GITHUB_OAUTH: the namespace of an individual GitHub user — a single login (human or bot, e.g. "alice"), addressed as github_oauth/{login} - PROVIDER_GITHUB_APP: the org/tenant namespace — its account is the org name (github_app/{org}), never a person - PROVIDER_GOOGLE_OIDC: Google Workspace domain - PROVIDER_SERVICE_PROFILE: owner is a CatalogServiceProfile; account is the profile name v1Phase: type: string enum: - PHASE_UNSPECIFIED - PHASE_STARTING - PHASE_RUNNING - PHASE_TASK_COMPLETE - PHASE_IDLE - PHASE_SLEEPING - PHASE_DESTROYING - PHASE_COMPLETED - PHASE_FAILED - PHASE_CANCELED default: PHASE_UNSPECIFIED description: The lifecycle state of an agent. securitySchemes: ApiKey: type: http scheme: bearer description: 'murmur API key: mur_.' ````