> ## 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. # Get agent status > Status returns an agent's current state. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agent/status 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/agent/status: post: tags: - MurmurService summary: Get agent status description: Status returns an agent's current state. operationId: MurmurService_Status requestBody: content: application/json: schema: $ref: '#/components/schemas/v1StatusRequest' required: true responses: '200': description: A successful response. content: application/json: schema: $ref: '#/components/schemas/v1AgentStatus' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/googleRpcStatus' components: schemas: v1StatusRequest: type: object properties: agentId: $ref: '#/components/schemas/v1AgentId' v1AgentStatus: type: object properties: agentId: $ref: '#/components/schemas/v1AgentId' phase: $ref: '#/components/schemas/v1Phase' agent: type: string title: agent persona (e.g. "programmer") description: type: string vmStopped: type: boolean vmDeleted: type: boolean description: >- True when the VM and its disk no longer exist. Takes precedence over vm_stopped: a destroyed VM would otherwise read as merely stopped. output: $ref: '#/components/schemas/v1AgentTaskOutput' version: type: string title: murmur-vm binary version running on the VM tasks: type: array items: $ref: '#/components/schemas/v1Task' title: current task checklist items progressAt: type: string format: date-time title: when the last progress was received currentDescription: type: string description: The task description the current turn is working on. queuedFollowUps: type: array items: type: string title: >- follow-up descriptions waiting in the queue for the current turn to finish shortId: type: string description: >- Short stable identifier for this agent, used in preview-URL subdomains. runCount: type: integer format: int32 title: total number of completed + in-progress runs sessionMode: $ref: '#/components/schemas/v1SessionMode' completionCheck: $ref: '#/components/schemas/v1CompletionCheck' onIdle: $ref: '#/components/schemas/v1OnIdle' model: type: string title: model override (e.g. "claude-sonnet-4-6") fastMode: type: boolean logErrorCount: type: integer format: int32 description: Count of ERROR-severity VM log entries. workspace: type: string description: workspace name (if spawned from a workspace preset). Display only. environment: type: string description: environment name. repos: type: array items: $ref: '#/components/schemas/murmurAgentV1Repo' title: >- per-repo branch state (clone_url, base_branch, branch, branch_created) dequeueStrategy: $ref: '#/components/schemas/v1DequeueStrategy' purpose: type: string description: |- One-sentence human-readable goal for this agent. Displayed in the dashboard for context. Not interpreted by the system. backend: type: string title: '"claude" or "codex"' serviceProfile: type: string description: >- Service profile name when the agent runs as a service profile. Empty for developer agents. nagError: type: string description: >- Last nag (completion-check) failure message. Non-empty when the most recent nag attempt failed (e.g. PAT/auth error, process launch error). Cleared at the start of each new turn so it only surfaces while the agent is idle after a failed nag. Customers polling status can use this field to understand why a completion check did not run. dashboardUrl: type: string description: >- Dashboard URL for this agent. Empty when the server has no public URL configured. failure: $ref: '#/components/schemas/v1AgentError' clientHint: $ref: '#/components/schemas/v1ClientHint' tags: type: array items: type: string description: Names of the tags attached to this agent. Empty if untagged. terminationSuggestedAt: type: string format: date-time description: >- When termination was suggested for this agent. Set means a suggestion is pending; unset means none. terminationSuggestedReason: type: string suggestTerminateMode: $ref: '#/components/schemas/v1SuggestTerminateMode' reasoningEffort: type: string description: Active reasoning-effort override. Empty means the backend default. serviceTier: type: string description: Active Codex service-tier override. Empty means the backend default. currentSpawnId: type: string description: >- The agent's current execution key. A respawn of the same slug starts a new execution under a new key, so this field changing is how a client detects a respawn. Empty on some serving paths. delayedFollowUps: type: array items: type: string description: >- Deferred messages still waiting on their deliver_at times, rendered as " (delivers at )". Separate from queued_follow_ups: a deferred message is scheduled future work, not work waiting on the current turn. description: >- The full state of an agent: identity, phase, output, tasks, cost, and failure details. Returned by the Status and Wait endpoints. 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. 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. v1AgentTaskOutput: type: object properties: prs: type: array items: $ref: '#/components/schemas/v1PRInfo' response: type: string cost: type: number format: double description: >- Cumulative list-price estimate across all turns: the notional value of the tokens at provider list rates, in USD. Not necessarily money anyone owes. duration: type: number format: double isError: type: boolean feedback: type: string description: >- Deprecated: agent meta-feedback, replaced by flight_messages. Populated only by older agent builds. uploads: type: array items: $ref: '#/components/schemas/v1Upload' description: Files uploaded to public storage during this task. inputTokens: type: string format: int64 description: >- Prompt tokens not served from cache, cumulative across all turns. The three token fields form a disjoint partition: total = input_tokens + cached_input_tokens + output_tokens, on both backends. cachedInputTokens: type: string format: int64 title: >- prompt tokens served from cache (Claude: cache_read; Codex: cached_input) outputTokens: type: string format: int64 title: generated/completion tokens (native on both backends) structuredOutput: type: string description: >- The agent's schema-validated task answer as a JSON document, set iff the spawn (or a follow-up) supplied an output_schema. Empty otherwise. This is the `result` member of the structured-output envelope; response above remains populated regardless. needsInput: type: string description: >- One-sentence prompt describing what the agent needs from a human when it is blocked awaiting a decision or answer; empty otherwise. Overwritten every turn, so an empty value clears a prior prompt. flightMessages: type: array items: $ref: '#/components/schemas/v1FlightMessage' description: >- Flight messages the latest turn emitted. Per-turn, not accumulated: each turn's messages replace the previous turn's. description: The result of a completed agent task. v1Task: type: object properties: id: type: string subject: type: string description: type: string status: $ref: '#/components/schemas/v1TaskStatus' blocks: type: array items: type: string title: IDs of tasks this task blocks blockedBy: type: array items: type: string title: IDs of tasks that block this task activation: $ref: '#/components/schemas/v1TaskActivation' persona: type: string description: >- Name of the persona that contributed this task (e.g. "programmer"). Empty for tasks from the spawn request, follow-ups, or task_create. A persona switch removes exactly the persona-tagged tasks and adds the new persona's, leaving all untagged tasks in place. dedupKey: type: string description: >- Stable identity of the external object this task tracks (e.g. a PR review thread). Tasks with the same key are de-duplicated within one delivery batch. Empty for caller-created tasks, which are never de-duplicated. ephemeral: type: boolean description: >- Ephemeral tasks live for exactly one run: created with the follow-up that delivers them and removed when that run completes. Set by the platform on per-thread PR comment and review tasks. description: A checklist item on the agent's task list. v1SessionMode: type: string enum: - SESSION_MODE_UNSPECIFIED - SESSION_MODE_AUTONOMOUS - SESSION_MODE_STREAMING default: SESSION_MODE_UNSPECIFIED description: |- SessionMode determines how the agent's coding session is executed. - SESSION_MODE_AUTONOMOUS: The agent runs each turn to completion and returns structured output. - SESSION_MODE_STREAMING: Long-lived interactive session; follow-ups stream into the live session. v1CompletionCheck: type: string enum: - COMPLETION_CHECK_UNSPECIFIED - COMPLETION_CHECK_NONE - COMPLETION_CHECK_ASSESSOR default: COMPLETION_CHECK_UNSPECIFIED description: |- CompletionCheck determines whether the agent re-checks completion after a task finishes, before entering idle behavior. - COMPLETION_CHECK_NONE: Proceed directly to idle behavior. - COMPLETION_CHECK_ASSESSOR: Fork session, run completion assessor up to 3 times. v1OnIdle: type: string enum: - ON_IDLE_UNSPECIFIED - ON_IDLE_SLEEP - ON_IDLE_TERMINATE - ON_IDLE_KEEP_ALIVE default: ON_IDLE_UNSPECIFIED description: |- OnIdle determines what happens when the agent has no more work after task completion (and optional completion check). - ON_IDLE_SLEEP: Hibernate/suspend VM, wait for follow-up or cancel. - ON_IDLE_TERMINATE: End the agent and destroy its VM. - ON_IDLE_KEEP_ALIVE: VM stays running, session stays live. Periodic session backup every 30m. murmurAgentV1Repo: type: object properties: cloneUrl: type: string title: canonical clone URL (always HTTPS, no .git suffix); the PR head repo baseBranch: type: string title: >- base branch on the base repo (base_clone_url when set, else clone_url) — what the PR targets and the working branch is cut from branch: type: string title: working branch the agent operates on branchCreated: type: boolean description: >- True when the platform created the working branch for this run, rather than adopting an existing one. conflictResolution: $ref: '#/components/schemas/v1ConflictResolution' baseCloneUrl: type: string description: >- Optional base repo: the repo the PR is opened against. Empty ⇒ a same-repo PR against clone_url's own base_branch (the default). When set ⇒ a cross-repo PR whose head is (clone_url, branch) and whose base is (base_clone_url, base_branch); clone_url must be a fork of base_clone_url (GitHub permits cross-repo PRs only within a fork network). Event routing (branch/file topics, commit/PR records) and the working branch's base both key to base_clone_url. description: >- A repository and its branch configuration. In workspace catalog entries, clone_url and base_branch are set. On spawn requests, only clone_url is required — an empty base_branch resolves to the repo's default branch. On statuses, all fields are populated. v1DequeueStrategy: type: string enum: - DEQUEUE_STRATEGY_UNSPECIFIED - DEQUEUE_STRATEGY_ALL - DEQUEUE_STRATEGY_ONE - DEQUEUE_STRATEGY_FIVE - DEQUEUE_STRATEGY_AUTO default: DEQUEUE_STRATEGY_UNSPECIFIED description: |- Controls how queued follow-up messages are drained between agent turns. - DEQUEUE_STRATEGY_UNSPECIFIED: Default: AUTO. - DEQUEUE_STRATEGY_ALL: Drain all queued follow-ups into one batch. - DEQUEUE_STRATEGY_ONE: Drain one follow-up per turn. - DEQUEUE_STRATEGY_FIVE: Drain up to five follow-ups per turn. - DEQUEUE_STRATEGY_AUTO: Drain up to five follow-ups of one kind per turn — manual follow-ups and auto-generated events are never delivered in the same turn (kind-boundary batching, capped at five). v1AgentError: type: object properties: type: $ref: '#/components/schemas/v1AgentFailureType' message: type: string description: One-sentence summary of the failure. repo: type: string title: offending repo "org/name", empty when not repo-scoped serviceProfile: type: string description: >- Service profile name when the failure occurred under a service profile; empty for developer agents. description: >- Structured failure details for an agent that failed — typically during setup, before its first turn. Returned on AgentStatus so clients can render an actionable message. v1ClientHint: type: object properties: surface: type: string description: The client surface (e.g. "murmur-cli", "murmur-mcp", "murmur-ui"). surfaceVersion: type: string title: >- that surface's build (e.g. "0.1+a1b2c3d4"); the UI sends its served version host: type: string title: >- embedding MCP host, normalized (e.g. "claude-code", "codex"); empty for non-MCP surfaces hostVersion: type: string title: >- that host's clientInfo.version (e.g. "0.131.0"); empty when host is empty description: >- Identifies the client surface that issued an action (CLI, MCP, dashboard). Display-only attribution — never an authorization input. v1SuggestTerminateMode: type: string enum: - SUGGEST_TERMINATE_MODE_UNSPECIFIED - SUGGEST_TERMINATE_MODE_SUGGEST - SUGGEST_TERMINATE_MODE_IMMEDIATE default: SUGGEST_TERMINATE_MODE_UNSPECIFIED description: >- - SUGGEST_TERMINATE_MODE_UNSPECIFIED: inherit (workspace, then the SUGGEST default) - SUGGEST_TERMINATE_MODE_SUGGEST: advisory only: the dashboard renders a delete button; a human decides - SUGGEST_TERMINATE_MODE_IMMEDIATE: terminate the agent immediately, no delete button 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. 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. 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 v1PRInfo: type: object properties: url: type: string title: type: string state: $ref: '#/components/schemas/v1PRState' checksStatus: $ref: '#/components/schemas/v1ChecksStatus' failedChecks: type: array items: type: string headBranch: type: string headSha: type: string repo: type: string description: >- Canonical HTTPS clone URL. Client-supplied, not a trust boundary — treat as descriptive metadata. reviewState: $ref: '#/components/schemas/v1PRReviewState' description: PRInfo identifies a pull request opened by an agent. v1Upload: type: object properties: url: type: string title: public HTTPS URL (e.g. "https://storage.googleapis.com/...") filename: type: string title: original filename (e.g. "diagram.png") runId: type: integer format: int32 description: >- The turn the file was uploaded on, matching Turn.run_id. 0 means the turn is unknown. description: A file the agent uploaded to public storage. v1FlightMessage: type: object properties: flight: type: string description: >- The flight the field was registered by, captured at injection time. Delivery targets this flight even if the registration changed mid-turn. field: type: string description: The registered field name the agent filled. value: type: string description: |- The agent's message text, verbatim (never empty — a null or empty field emits no message). description: |- FlightMessage is one filled-in message extracted from a completed turn's structured output. v1TaskStatus: type: string enum: - TASK_STATUS_UNSPECIFIED - TASK_STATUS_PENDING - TASK_STATUS_IN_PROGRESS - TASK_STATUS_COMPLETED - TASK_STATUS_DELETED default: TASK_STATUS_UNSPECIFIED description: TaskStatus is the lifecycle state of a checklist task. v1TaskActivation: type: object properties: filesModified: $ref: '#/components/schemas/v1FilesModified' description: >- Defines when a task becomes active. At most one condition may be set; unset means always active. v1ConflictResolution: type: string enum: - CONFLICT_RESOLUTION_UNSPECIFIED - CONFLICT_RESOLUTION_MERGE - CONFLICT_RESOLUTION_REBASE - CONFLICT_RESOLUTION_NONE default: CONFLICT_RESOLUTION_UNSPECIFIED description: |- ConflictResolution determines how file-changed conflicts are resolved. - CONFLICT_RESOLUTION_UNSPECIFIED: catalog default — server treats as MERGE - CONFLICT_RESOLUTION_NONE: opt out of file-changed notifications v1AgentFailureType: type: string enum: - AGENT_FAILURE_TYPE_UNSPECIFIED - AGENT_FAILURE_TYPE_REPO_NOT_FOUND - AGENT_FAILURE_TYPE_AUTH_EXPIRED - AGENT_FAILURE_TYPE_PERMISSION - AGENT_FAILURE_TYPE_INVALID_INPUT - AGENT_FAILURE_TYPE_SETUP default: AGENT_FAILURE_TYPE_UNSPECIFIED description: >- Classifies why an agent failed, so clients can present a friendly message and the right remediation without parsing error strings. - AGENT_FAILURE_TYPE_UNSPECIFIED: unknown / other — show the message verbatim - AGENT_FAILURE_TYPE_REPO_NOT_FOUND: repo missing or credentials have no access (GitHub 404) - AGENT_FAILURE_TYPE_AUTH_EXPIRED: credentials expired or revoked (GitHub 401) - AGENT_FAILURE_TYPE_PERMISSION: authenticated but lacks access / protected branch - AGENT_FAILURE_TYPE_INVALID_INPUT: bad config (e.g. base_branch is not a branch) - AGENT_FAILURE_TYPE_SETUP: other setup-phase failure v1PRState: type: string enum: - PR_STATE_UNSPECIFIED - PR_STATE_OPEN - PR_STATE_MERGED - PR_STATE_CLOSED default: PR_STATE_UNSPECIFIED description: PRState is the lifecycle state of a pull request. v1ChecksStatus: type: string enum: - CHECKS_STATUS_UNSPECIFIED - CHECKS_STATUS_PASSED - CHECKS_STATUS_FAILED - CHECKS_STATUS_PENDING default: CHECKS_STATUS_UNSPECIFIED description: >- The aggregate CI status of a pull request, derived from the recorded checks at the PR's current head commit. - CHECKS_STATUS_UNSPECIFIED: no check has been recorded for the head SHA yet - CHECKS_STATUS_PASSED: every recorded check concluded non-failure - CHECKS_STATUS_FAILED: at least one recorded check failed - CHECKS_STATUS_PENDING: a recorded check is still in progress v1PRReviewState: type: string enum: - PR_REVIEW_STATE_UNSPECIFIED - PR_REVIEW_STATE_APPROVED - PR_REVIEW_STATE_CHANGES_REQUESTED - PR_REVIEW_STATE_COMMENTED default: PR_REVIEW_STATE_UNSPECIFIED description: PRReviewState classifies the review disposition of a pull request. v1FilesModified: type: object properties: pattern: type: string title: glob pattern for file paths; empty = any file description: |- FilesModified activates a task when the agent pushes changes. Run-scoped: evaluated against pushes in the current run only. securitySchemes: ApiKey: type: http scheme: bearer description: 'murmur API key: mur_.' ````