Runs
Verified request, response and authorization contracts.
A Run belongs to a Task. Follow-ups, manual reruns, automatic retries, Cloud lifetime rollovers and pauses create distinct Run IDs, so follow the Task’s Runs rather than one Run. Read one Run you already know with GET /api/runs/{runId}; list the Task’s Runs to find its successors, then fetch a Run’s events/messages. All resource paths below use UUIDs unless noted.
Examples use the environment variables from Overview. UUID placeholders must be replaced with your own IDs.
GET /api/tasks/{id}/runs
Auth: Workspace member with access to this resource.
Request: Path: Task ID. No body.
Response: RunResponse array, newest first.
Status: 200. Authentication and resource-access errors follow Overview.
A retry, a Cloud lifetime rollover or a pause adds a successor Run whose parent_run_id is the Run it continues. The predecessor ends as failed (a retry keeps its own failure_reason; a rollover uses provider_lifetime_rollover) or, for a pause, as cancelled with user_paused. The successor starts as queued, deferred or paused. Retries increase attempt up to max_attempts; rollovers keep the same attempt. While any Run is queued, dispatched, running or deferred, the Task is still working. When none is, the newest Run is the outcome: completed has a reply in the Task messages, failed and cancelled carry error and failure_reason (a plain cancel by a person has neither), and paused waits for resume.
curl -sS -X GET "$MELSO_URL/api/tasks/$ID/runs" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"GET /api/runs/{runId}
Auth: Workspace member with access to the Run’s Task, under the same rules as GET /api/tasks/{id}/runs. A workspace API key reads Runs of its own workspace.
Request: Path: Run UUID. No body.
Response: RunResponse, identical to the Run’s item in GET /api/tasks/{id}/runs, including usage and attribution.
Status: 200; 400 invalid UUID; 404 unknown Run. A Run the caller may not see (another workspace, a private Area the caller is not in, an isolated Task for another Task’s Run) returns the same 404. Authentication errors follow Overview.
Use it to poll a Run you already know, such as the run_id a create or follow-up returned. When it ends, list the Task’s Runs: a retry, rollover or pause continues in a successor Run whose parent_run_id is this Run’s ID.
curl -sS -X GET "$MELSO_URL/api/runs/$RUN_ID" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"GET /api/runs/{runId}/events
Auth: Workspace member with access to this resource.
Request: Path: Run UUID. No pagination parameters.
Response: {events:RunEventPayload[]}.
Status: 200; 400 invalid UUID. Authentication and resource-access errors follow Overview.
curl -sS -X GET "$MELSO_URL/api/runs/$RUN_ID/events" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"GET /api/runs/{runId}/messages
Auth: Workspace member with access to this resource.
Request: Path: Run UUID; optional since:integer query.
Response: RunMessagePayload array.
Status: 200. Authentication and resource-access errors follow Overview.
curl -sS -X GET "$MELSO_URL/api/runs/$RUN_ID/messages" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"POST /api/runs/{runId}/cancel
Auth: Workspace member with access to this resource.
Request: Path: Run UUID. Query parameters, not a JSON body: optional task_id=<Task UUID> rejects a Run from another Task; cancelling a queued follow-up uses expected_status=queued plus task_id and queue_action=edit|remove.
Response: RunResponse plus optional cancelled_input:{task_id:UUID,message_id:UUID,content:string,restore_to_input:boolean,attachments:object[]}. Cancelling a Run that already ended returns it unchanged.
Status: 200; 400 invalid query parameters; 404 unknown Run; 409 mismatched Task or a follow-up that is no longer queued. Authentication and resource-access errors follow Overview.
curl -sS -X POST "$MELSO_URL/api/runs/$RUN_ID/cancel?task_id=$ID" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"POST /api/runs/{runId}/pause
Auth: Workspace member with access to this resource.
Request: Path: Run UUID.
Response: RunResponse for the Run it acted on. A live Cloud Run drains first and keeps its status until the worker saves; it then ends cancelled with user_paused and a paused successor appears in the Task’s Runs. A queued or deferred Run is cancelled with user_paused; an already paused Run is returned unchanged.
Status: 200; 409 incompatible Run state. Authentication and resource-access errors follow Overview.
curl -sS -X POST "$MELSO_URL/api/runs/$RUN_ID/pause" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" -d '{}'POST /api/tasks/{id}/resume
Auth: Human workspace member; rejects Run and MCP actors.
Request: Path: Task UUID. No execution override.
Response: RunResponse for the resumed successor, now queued.
Status: 200; 409 nothing resumable. Authentication and resource-access errors follow Overview.
curl -sS -X POST "$MELSO_URL/api/tasks/$ID/resume" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" -d '{}'POST /api/tasks/{id}/rerun
Auth: Workspace member with access to this resource.
Request: run_id:UUID: historical source Run in this Task.
Response: RunResponse for the new attempt.
Status: 202; 400 invalid source; 403 execution denied. Authentication and resource-access errors follow Overview.
curl -sS -X POST "$MELSO_URL/api/tasks/$ID/rerun" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" -d '{"run_id":"00000000-0000-4000-8000-000000000001"}'GET /api/tasks/{id}/execution
Auth: Human workspace member; rejects Run and MCP actors.
Request: Path: Task ID.
Response: {execution:TaskExecutionSettings|null}.
Status: 200. Authentication and resource-access errors follow Overview.
curl -sS -X GET "$MELSO_URL/api/tasks/$ID/execution" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"PUT /api/tasks/{id}/execution
Auth: Human workspace member; rejects Run and MCP actors.
Request: harness:string, optional model:string, thinking_level:string, service_tier:string.
Response: {execution:TaskExecutionSettings}.
Status: 200; 400 invalid selection. Authentication and resource-access errors follow Overview.
curl -sS -X PUT "$MELSO_URL/api/tasks/$ID/execution" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" -d '{"harness":"codex"}'POST /api/tasks/{id}/start
Auth: Human workspace member; rejects Run and MCP actors.
Request: Optional top-level harness:string, model:string, thinking_level:string, service_tier:string (TaskExecutionRequest). Cannot override max_attempts. Requires saved conversation instructions and an idle open Task.
Response: {run:RunResponse,execution?:TaskExecutionSettings}.
Status: 202; 400 no instructions/invalid selection; 409 not idle or no target. Authentication and resource-access errors follow Overview.
curl -sS -X POST "$MELSO_URL/api/tasks/$ID/start" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID" \
-H "Content-Type: application/json" -d '{}'GET /api/tasks/{id}/queue
Auth: Workspace member with access to this resource.
Request: Path: Task UUID.
Response: TaskRunQueueResponse.
Status: 200. Authentication and resource-access errors follow Overview.
curl -sS -X GET "$MELSO_URL/api/tasks/$ID/queue" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"DELETE /api/tasks/{id}/queue
Auth: Workspace member with access to this resource.
Request: Path: Task UUID.
Response: Empty.
Status: 204. Authentication and resource-access errors follow Overview.
curl -sS -X DELETE "$MELSO_URL/api/tasks/$ID/queue" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"RunResponse
Source: server/internal/handler/run_response.go (RunResponse). Referenced nested objects retain their handler-defined fields; clients should tolerate additional fields.
| Field | JSON type |
|---|---|
access | RunAccessReceipt or null (may be omitted) |
funding_source | string (may be omitted) |
hosted_gateway | HostedGatewayExecution or null (may be omitted) |
provider_account_id | string (may be omitted) |
id | string |
execution_owner_id | string |
worker_id | string |
model | string (may be omitted) |
thinking_level | string (may be omitted) |
service_tier | string (may be omitted) |
execution_receipt | RunExecutionReceipt or null (may be omitted) |
task_id | string |
task_identifier | string (may be omitted) |
workspace_id | string |
plugin_execution_manifest | PluginExecutionManifestData or null (may be omitted) |
remote_mcp_connections | RemoteMCPConnection[] (may be omitted) |
remote_mcp_daemon_token | string (may be omitted) |
github_checkout_token | string (may be omitted) |
github_agent_write_token | string (may be omitted) |
github_credential_grant | string (may be omitted) |
github_pull_request_read_token | string (may be omitted) |
workspace_context | string (may be omitted) |
thread_name | string (may be omitted) |
status | string |
dispatched_at | string or null |
started_at | string or null |
completed_at | string or null |
result | any |
error | string or null |
failure_reason | string (may be omitted) |
attempt | integer |
max_attempts | integer |
parent_run_id | string or null (may be omitted) |
execution | RunConfiguration or null (may be omitted) |
connected_apps | ConnectedAppData[] (may be omitted) |
repos | RepoData[] (may be omitted) |
secret_values | string[] (may be omitted) |
vault_items | RunVaultItem[] (may be omitted) |
vault_files | RunVaultFile[] (may be omitted) |
repository_environments | RunRepositoryEnvironment[] (may be omitted) |
area_id | string (may be omitted) |
area_title | string (may be omitted) |
area_description | string (may be omitted) |
area_resources | AreaResourceData[] (may be omitted) |
created_at | string |
prior_session_id | string (may be omitted) |
prior_work_dir | string (may be omitted) |
prior_session_resume_unavailable | boolean (may be omitted) |
work_dir | string (may be omitted) |
relative_work_dir | string (may be omitted) |
branch_name | string (may be omitted) |
trigger_message_id | string or null (may be omitted) |
coalesced_message_ids | string[] (may be omitted) |
coalesced_messages | CoalescedMessageData[] (may be omitted) |
delivered_message_ids | string[] |
trigger_thread_id | string (may be omitted) |
trigger_message_content | string (may be omitted) |
trigger_summary | string or null (may be omitted) |
trigger_author_type | string (may be omitted) |
trigger_author_name | string (may be omitted) |
new_comment_count | integer (may be omitted) |
new_comments_since | string (may be omitted) |
chat_message | string (may be omitted) |
chat_message_attachments | ChatAttachmentMeta[] (may be omitted) |
chat_transcript_injected | boolean (may be omitted) |
chat_transcript | ChatTranscriptMessage[] (may be omitted) |
automation_invocation_id | string (may be omitted) |
automation_id | string (may be omitted) |
automation_title | string (may be omitted) |
automation_description | string (may be omitted) |
automation_source | string (may be omitted) |
automation_trigger_payload | JSON (may be omitted) |
require_pr_checks_watch | boolean (may be omitted) |
is_github_pr_review_child | boolean (may be omitted) |
interaction_continuation | InteractionContinuationData or null (may be omitted) |
continuation_kind | string (may be omitted) |
requesting_user_name | string (may be omitted) |
requesting_user_profile_description | string (may be omitted) |
initiator_type | string (may be omitted) |
initiator_id | string (may be omitted) |
initiator_name | string (may be omitted) |
initiator_email | string (may be omitted) |
kind | string |
attribution | RunAttribution or null (may be omitted) |
usage | RunUsageData[] (may be omitted) |
auth_token | string (may be omitted) |
mount_fs_token | string (may be omitted) |
TaskRunQueueResponse
Source: server/internal/handler/task_input.go (TaskRunQueueResponse). Referenced nested objects retain their handler-defined fields; clients should tolerate additional fields.
| Field | JSON type |
|---|---|
run_id | string (may be omitted) |
status | string (may be omitted) |
created_at | string (may be omitted) |
queued_runs | QueuedRunResponse[] (may be omitted) |
GET /api/tasks/{id}/usage
Auth: Workspace member with access to this resource.
Request: No body.
Response: Object of token counters: total_input_tokens, total_output_tokens, total_cache_read_tokens, total_cache_write_tokens, cost_usd_ticks, uncosted_input_tokens, uncosted_output_tokens, uncosted_cache_read_tokens, uncosted_cache_write_tokens, run_count (integers).
Status: 200. Authentication and resource-access errors follow Overview.
curl -sS -X GET "$MELSO_URL/api/tasks/$ID/usage" \
-H "Authorization: Bearer $MELSO_TOKEN" -H "X-Workspace-ID: $WORKSPACE_ID"RunEventPayload
Source: server/pkg/protocol/messages.go (RunEventPayload). Referenced nested objects retain their handler-defined fields; clients should tolerate additional fields.
| Field | JSON type |
|---|---|
id | string |
run_id | string |
task_id | string (may be omitted) |
source | string |
kind | string |
label | string (may be omitted) |
detail | object (may be omitted) |
occurred_at | string |
source_at | string (may be omitted) |
recorded_at | string |
RunMessagePayload
Source: server/pkg/protocol/messages.go (RunMessagePayload). Referenced nested objects retain their handler-defined fields; clients should tolerate additional fields.
| Field | JSON type |
|---|---|
run_id | string |
task_id | string (may be omitted) |
seq | integer |
type | string |
tool | string (may be omitted) |
content | string (may be omitted) |
input | object (may be omitted) |
output | string (may be omitted) |
created_at | string (may be omitted) |
QueuedRunResponse
Source: server/internal/handler/task_input.go (QueuedRunResponse). Referenced nested objects retain their handler-defined fields; clients should tolerate additional fields.
| Field | JSON type |
|---|---|
run_id | string |
status | string |
created_at | string |
message_id | string (may be omitted) |
content | string (may be omitted) |
TaskExecutionSettings
Source: server/internal/service/run_execution.go (TaskExecutionSettings). Referenced nested objects retain their handler-defined fields; clients should tolerate additional fields.
| Field | JSON type |
|---|---|
version | string |
harness | string |
model | string |
thinking_level | string |
service_tier | string |