Wait for an agent phase
curl --request POST \
--url https://api.murmur.dev/v1/agent/wait \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agentId": {
"tenant": {
"provider": "PROVIDER_UNSPECIFIED",
"org": "<string>"
},
"ownerProvider": "PROVIDER_UNSPECIFIED",
"account": "<string>",
"agent": [
"<string>"
],
"workspace": "<string>"
},
"targetPhase": "PHASE_UNSPECIFIED"
}
'import requests
url = "https://api.murmur.dev/v1/agent/wait"
payload = {
"agentId": {
"tenant": {
"provider": "PROVIDER_UNSPECIFIED",
"org": "<string>"
},
"ownerProvider": "PROVIDER_UNSPECIFIED",
"account": "<string>",
"agent": ["<string>"],
"workspace": "<string>"
},
"targetPhase": "PHASE_UNSPECIFIED"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agentId: {
tenant: {provider: 'PROVIDER_UNSPECIFIED', org: '<string>'},
ownerProvider: 'PROVIDER_UNSPECIFIED',
account: '<string>',
agent: ['<string>'],
workspace: '<string>'
},
targetPhase: 'PHASE_UNSPECIFIED'
})
};
fetch('https://api.murmur.dev/v1/agent/wait', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.murmur.dev/v1/agent/wait",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agentId' => [
'tenant' => [
'provider' => 'PROVIDER_UNSPECIFIED',
'org' => '<string>'
],
'ownerProvider' => 'PROVIDER_UNSPECIFIED',
'account' => '<string>',
'agent' => [
'<string>'
],
'workspace' => '<string>'
],
'targetPhase' => 'PHASE_UNSPECIFIED'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.murmur.dev/v1/agent/wait"
payload := strings.NewReader("{\n \"agentId\": {\n \"tenant\": {\n \"provider\": \"PROVIDER_UNSPECIFIED\",\n \"org\": \"<string>\"\n },\n \"ownerProvider\": \"PROVIDER_UNSPECIFIED\",\n \"account\": \"<string>\",\n \"agent\": [\n \"<string>\"\n ],\n \"workspace\": \"<string>\"\n },\n \"targetPhase\": \"PHASE_UNSPECIFIED\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.murmur.dev/v1/agent/wait")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"agentId\": {\n \"tenant\": {\n \"provider\": \"PROVIDER_UNSPECIFIED\",\n \"org\": \"<string>\"\n },\n \"ownerProvider\": \"PROVIDER_UNSPECIFIED\",\n \"account\": \"<string>\",\n \"agent\": [\n \"<string>\"\n ],\n \"workspace\": \"<string>\"\n },\n \"targetPhase\": \"PHASE_UNSPECIFIED\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.murmur.dev/v1/agent/wait")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agentId\": {\n \"tenant\": {\n \"provider\": \"PROVIDER_UNSPECIFIED\",\n \"org\": \"<string>\"\n },\n \"ownerProvider\": \"PROVIDER_UNSPECIFIED\",\n \"account\": \"<string>\",\n \"agent\": [\n \"<string>\"\n ],\n \"workspace\": \"<string>\"\n },\n \"targetPhase\": \"PHASE_UNSPECIFIED\"\n}"
response = http.request(request)
puts response.read_body{
"agentId": {
"tenant": {
"provider": "PROVIDER_UNSPECIFIED",
"org": "<string>"
},
"ownerProvider": "PROVIDER_UNSPECIFIED",
"account": "<string>",
"agent": [
"<string>"
],
"workspace": "<string>"
},
"phase": "PHASE_UNSPECIFIED",
"agent": "<string>",
"description": "<string>",
"vmStopped": true,
"vmDeleted": true,
"output": {
"prs": [
{
"url": "<string>",
"title": "<string>",
"state": "PR_STATE_UNSPECIFIED",
"checksStatus": "CHECKS_STATUS_UNSPECIFIED",
"failedChecks": [
"<string>"
],
"headBranch": "<string>",
"headSha": "<string>",
"repo": "<string>",
"reviewState": "PR_REVIEW_STATE_UNSPECIFIED"
}
],
"response": "<string>",
"cost": 123,
"duration": 123,
"isError": true,
"feedback": "<string>",
"uploads": [
{
"url": "<string>",
"filename": "<string>",
"runId": 123
}
],
"inputTokens": "<string>",
"cachedInputTokens": "<string>",
"outputTokens": "<string>",
"structuredOutput": "<string>",
"needsInput": "<string>",
"flightMessages": [
{
"flight": "<string>",
"field": "<string>",
"value": "<string>"
}
]
},
"version": "<string>",
"tasks": [
{
"id": "<string>",
"subject": "<string>",
"description": "<string>",
"status": "TASK_STATUS_UNSPECIFIED",
"blocks": [
"<string>"
],
"blockedBy": [
"<string>"
],
"activation": {
"filesModified": {
"pattern": "<string>"
}
},
"persona": "<string>",
"dedupKey": "<string>",
"ephemeral": true
}
],
"progressAt": "2023-11-07T05:31:56Z",
"currentDescription": "<string>",
"queuedFollowUps": [
"<string>"
],
"shortId": "<string>",
"runCount": 123,
"sessionMode": "SESSION_MODE_UNSPECIFIED",
"completionCheck": "COMPLETION_CHECK_UNSPECIFIED",
"onIdle": "ON_IDLE_UNSPECIFIED",
"model": "<string>",
"fastMode": true,
"logErrorCount": 123,
"workspace": "<string>",
"environment": "<string>",
"repos": [
{
"cloneUrl": "<string>",
"baseBranch": "<string>",
"branch": "<string>",
"branchCreated": true,
"conflictResolution": "CONFLICT_RESOLUTION_UNSPECIFIED",
"baseCloneUrl": "<string>"
}
],
"dequeueStrategy": "DEQUEUE_STRATEGY_UNSPECIFIED",
"purpose": "<string>",
"backend": "<string>",
"serviceProfile": "<string>",
"nagError": "<string>",
"dashboardUrl": "<string>",
"failure": {
"type": "AGENT_FAILURE_TYPE_UNSPECIFIED",
"message": "<string>",
"repo": "<string>",
"serviceProfile": "<string>"
},
"clientHint": {
"surface": "<string>",
"surfaceVersion": "<string>",
"host": "<string>",
"hostVersion": "<string>"
},
"tags": [
"<string>"
],
"terminationSuggestedAt": "2023-11-07T05:31:56Z",
"terminationSuggestedReason": "<string>",
"suggestTerminateMode": "SUGGEST_TERMINATE_MODE_UNSPECIFIED",
"reasoningEffort": "<string>",
"serviceTier": "<string>",
"currentSpawnId": "<string>",
"delayedFollowUps": [
"<string>"
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}Endpoints
Wait for an agent phase
Wait blocks until an agent reaches a phase that needs attention or the specified target phase. Server-side polling, unary response.
POST
/
v1
/
agent
/
wait
Wait for an agent phase
curl --request POST \
--url https://api.murmur.dev/v1/agent/wait \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agentId": {
"tenant": {
"provider": "PROVIDER_UNSPECIFIED",
"org": "<string>"
},
"ownerProvider": "PROVIDER_UNSPECIFIED",
"account": "<string>",
"agent": [
"<string>"
],
"workspace": "<string>"
},
"targetPhase": "PHASE_UNSPECIFIED"
}
'import requests
url = "https://api.murmur.dev/v1/agent/wait"
payload = {
"agentId": {
"tenant": {
"provider": "PROVIDER_UNSPECIFIED",
"org": "<string>"
},
"ownerProvider": "PROVIDER_UNSPECIFIED",
"account": "<string>",
"agent": ["<string>"],
"workspace": "<string>"
},
"targetPhase": "PHASE_UNSPECIFIED"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agentId: {
tenant: {provider: 'PROVIDER_UNSPECIFIED', org: '<string>'},
ownerProvider: 'PROVIDER_UNSPECIFIED',
account: '<string>',
agent: ['<string>'],
workspace: '<string>'
},
targetPhase: 'PHASE_UNSPECIFIED'
})
};
fetch('https://api.murmur.dev/v1/agent/wait', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.murmur.dev/v1/agent/wait",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agentId' => [
'tenant' => [
'provider' => 'PROVIDER_UNSPECIFIED',
'org' => '<string>'
],
'ownerProvider' => 'PROVIDER_UNSPECIFIED',
'account' => '<string>',
'agent' => [
'<string>'
],
'workspace' => '<string>'
],
'targetPhase' => 'PHASE_UNSPECIFIED'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.murmur.dev/v1/agent/wait"
payload := strings.NewReader("{\n \"agentId\": {\n \"tenant\": {\n \"provider\": \"PROVIDER_UNSPECIFIED\",\n \"org\": \"<string>\"\n },\n \"ownerProvider\": \"PROVIDER_UNSPECIFIED\",\n \"account\": \"<string>\",\n \"agent\": [\n \"<string>\"\n ],\n \"workspace\": \"<string>\"\n },\n \"targetPhase\": \"PHASE_UNSPECIFIED\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.murmur.dev/v1/agent/wait")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"agentId\": {\n \"tenant\": {\n \"provider\": \"PROVIDER_UNSPECIFIED\",\n \"org\": \"<string>\"\n },\n \"ownerProvider\": \"PROVIDER_UNSPECIFIED\",\n \"account\": \"<string>\",\n \"agent\": [\n \"<string>\"\n ],\n \"workspace\": \"<string>\"\n },\n \"targetPhase\": \"PHASE_UNSPECIFIED\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.murmur.dev/v1/agent/wait")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agentId\": {\n \"tenant\": {\n \"provider\": \"PROVIDER_UNSPECIFIED\",\n \"org\": \"<string>\"\n },\n \"ownerProvider\": \"PROVIDER_UNSPECIFIED\",\n \"account\": \"<string>\",\n \"agent\": [\n \"<string>\"\n ],\n \"workspace\": \"<string>\"\n },\n \"targetPhase\": \"PHASE_UNSPECIFIED\"\n}"
response = http.request(request)
puts response.read_body{
"agentId": {
"tenant": {
"provider": "PROVIDER_UNSPECIFIED",
"org": "<string>"
},
"ownerProvider": "PROVIDER_UNSPECIFIED",
"account": "<string>",
"agent": [
"<string>"
],
"workspace": "<string>"
},
"phase": "PHASE_UNSPECIFIED",
"agent": "<string>",
"description": "<string>",
"vmStopped": true,
"vmDeleted": true,
"output": {
"prs": [
{
"url": "<string>",
"title": "<string>",
"state": "PR_STATE_UNSPECIFIED",
"checksStatus": "CHECKS_STATUS_UNSPECIFIED",
"failedChecks": [
"<string>"
],
"headBranch": "<string>",
"headSha": "<string>",
"repo": "<string>",
"reviewState": "PR_REVIEW_STATE_UNSPECIFIED"
}
],
"response": "<string>",
"cost": 123,
"duration": 123,
"isError": true,
"feedback": "<string>",
"uploads": [
{
"url": "<string>",
"filename": "<string>",
"runId": 123
}
],
"inputTokens": "<string>",
"cachedInputTokens": "<string>",
"outputTokens": "<string>",
"structuredOutput": "<string>",
"needsInput": "<string>",
"flightMessages": [
{
"flight": "<string>",
"field": "<string>",
"value": "<string>"
}
]
},
"version": "<string>",
"tasks": [
{
"id": "<string>",
"subject": "<string>",
"description": "<string>",
"status": "TASK_STATUS_UNSPECIFIED",
"blocks": [
"<string>"
],
"blockedBy": [
"<string>"
],
"activation": {
"filesModified": {
"pattern": "<string>"
}
},
"persona": "<string>",
"dedupKey": "<string>",
"ephemeral": true
}
],
"progressAt": "2023-11-07T05:31:56Z",
"currentDescription": "<string>",
"queuedFollowUps": [
"<string>"
],
"shortId": "<string>",
"runCount": 123,
"sessionMode": "SESSION_MODE_UNSPECIFIED",
"completionCheck": "COMPLETION_CHECK_UNSPECIFIED",
"onIdle": "ON_IDLE_UNSPECIFIED",
"model": "<string>",
"fastMode": true,
"logErrorCount": 123,
"workspace": "<string>",
"environment": "<string>",
"repos": [
{
"cloneUrl": "<string>",
"baseBranch": "<string>",
"branch": "<string>",
"branchCreated": true,
"conflictResolution": "CONFLICT_RESOLUTION_UNSPECIFIED",
"baseCloneUrl": "<string>"
}
],
"dequeueStrategy": "DEQUEUE_STRATEGY_UNSPECIFIED",
"purpose": "<string>",
"backend": "<string>",
"serviceProfile": "<string>",
"nagError": "<string>",
"dashboardUrl": "<string>",
"failure": {
"type": "AGENT_FAILURE_TYPE_UNSPECIFIED",
"message": "<string>",
"repo": "<string>",
"serviceProfile": "<string>"
},
"clientHint": {
"surface": "<string>",
"surfaceVersion": "<string>",
"host": "<string>",
"hostVersion": "<string>"
},
"tags": [
"<string>"
],
"terminationSuggestedAt": "2023-11-07T05:31:56Z",
"terminationSuggestedReason": "<string>",
"suggestTerminateMode": "SUGGEST_TERMINATE_MODE_UNSPECIFIED",
"reasoningEffort": "<string>",
"serviceTier": "<string>",
"currentSpawnId": "<string>",
"delayedFollowUps": [
"<string>"
]
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}Authorizations
murmur API key: mur_<key_id>.
Body
application/json
Identifies an agent. The identity is (tenant, workspace, owner, agent path); the workspace scopes the agent's repos, environment, and base branches.
Show child attributes
Show child attributes
The lifecycle state of an agent.
Available options:
PHASE_UNSPECIFIED, PHASE_STARTING, PHASE_RUNNING, PHASE_TASK_COMPLETE, PHASE_IDLE, PHASE_SLEEPING, PHASE_DESTROYING, PHASE_COMPLETED, PHASE_FAILED, PHASE_CANCELED Response
A successful response.
The full state of an agent: identity, phase, output, tasks, cost, and failure details. Returned by the Status and Wait endpoints.
Identifies an agent. The identity is (tenant, workspace, owner, agent path); the workspace scopes the agent's repos, environment, and base branches.
Show child attributes
Show child attributes
The lifecycle state of an agent.
Available options:
PHASE_UNSPECIFIED, PHASE_STARTING, PHASE_RUNNING, PHASE_TASK_COMPLETE, PHASE_IDLE, PHASE_SLEEPING, PHASE_DESTROYING, PHASE_COMPLETED, PHASE_FAILED, PHASE_CANCELED True when the VM and its disk no longer exist. Takes precedence over vm_stopped: a destroyed VM would otherwise read as merely stopped.
The result of a completed agent task.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The task description the current turn is working on.
Short stable identifier for this agent, used in preview-URL subdomains.
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.
Available options:
SESSION_MODE_UNSPECIFIED, SESSION_MODE_AUTONOMOUS, SESSION_MODE_STREAMING 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.
Available options:
COMPLETION_CHECK_UNSPECIFIED, COMPLETION_CHECK_NONE, COMPLETION_CHECK_ASSESSOR 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.
Available options:
ON_IDLE_UNSPECIFIED, ON_IDLE_SLEEP, ON_IDLE_TERMINATE, ON_IDLE_KEEP_ALIVE Count of ERROR-severity VM log entries.
workspace name (if spawned from a workspace preset). Display only.
environment name.
Show child attributes
Show child attributes
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).
Available options:
DEQUEUE_STRATEGY_UNSPECIFIED, DEQUEUE_STRATEGY_ALL, DEQUEUE_STRATEGY_ONE, DEQUEUE_STRATEGY_FIVE, DEQUEUE_STRATEGY_AUTO One-sentence human-readable goal for this agent. Displayed in the dashboard for context. Not interpreted by the system.
Service profile name when the agent runs as a service profile. Empty for developer agents.
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.
Dashboard URL for this agent. Empty when the server has no public URL configured.
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.
Show child attributes
Show child attributes
Identifies the client surface that issued an action (CLI, MCP, dashboard). Display-only attribution — never an authorization input.
Show child attributes
Show child attributes
Names of the tags attached to this agent. Empty if untagged.
When termination was suggested for this agent. Set means a suggestion is pending; unset means none.
-
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
Available options:
SUGGEST_TERMINATE_MODE_UNSPECIFIED, SUGGEST_TERMINATE_MODE_SUGGEST, SUGGEST_TERMINATE_MODE_IMMEDIATE Active reasoning-effort override. Empty means the backend default.
Active Codex service-tier override. Empty means the backend default.
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.
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.