API referenceRuns
Retrieve run progress
GET
/api/v1/runs/{run_id}/progressRetrieve a stable snapshot of the state an external orchestrator needs to understand a run: lifecycle, active plan and enforcement position, bounded semantic progress, child work, and recent tool activity.
The semantic progress projection deliberately excludes raw model or provider checkpoints, policy internals, debug events, evidence digests, and tool arguments. Treat it as a resumable progress view, not an execution replay format.
Child groups are newest-first, and both groups and child memberships are capped at 100 entries each. Tool activity contains the latest 100 calls in chronological order. Read each truncated flag and its accompanying total before assuming the snapshot is complete.
semantic_progress is null for coordinating team runs that do not own an agent task checkpoint. It is present for agent runs from admission through terminal settlement.
Required access
Credentials: service principal, delegated token, user session
Scope: runs:read
Uses the same organization-isolated visibility rule as retrieving the run itself; an identifier from another organization answers 404.
AuthorizationBearer <token>
An organization-owned automation key, prefixed gsmc_sk_. Already bound to one organization, so it needs no X-Org-Id header. It carries no user identity: it never reaches a private resource however it is scoped, and a run it starts has no user for an interactive tool to reach.
In: header
Path Parameters
run_id*Run Id
Header Parameters
X-Org-Id?|
Selects the active organization for a credential that belongs to more than one. Service-principal keys are bound to a single organization and ignore it.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/runs/0/progress" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"{ "run": { "id": 1, "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba", "invocable_type": "agent", "actor_principal_type": "agent", "service_principal_id": "0d57b427-9ed2-4a5e-b0bd-32c8ce299b8e", "oauth_client_id": "727760ca-b97d-449c-90e5-7773c8142d5d", "parent_run_id": 1, "root_run_id": 1, "call_depth": 0, "agent_config_revision": 1, "agent_config_digest": "string", "tool_approval_mode": "auto", "tool_approval_mode_revision": 1, "status": "awaiting_plan_approval", "created_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "duration_seconds": 0, "last_heartbeat": "2019-08-24T14:15:22Z", "input_data": {}, "output_data": {}, "artifacts": [ {} ], "verification_status": "not_evaluated", "verification_summary": "string", "verification_checks_passed": 0, "verification_checks_total": 0, "verification_evaluated_at": "2019-08-24T14:15:22Z", "error": "string", "error_category": "string", "error_code": "string", "error_retryable": true, "limit_detail": { "error": "limit_exceeded", "limit_type": "budget.hard_stop", "scope": "call_tree", "message": "string", "scope_id": "string", "limit": 0, "actual": 0, "retry_after_seconds": 0, "resets_at": "2019-08-24T14:15:22Z" }, "tool_retry_intervention": { "code": "string", "message": "string", "retryable": true, "suggested_action": "string", "tool_label": "string", "policy_event_type": "string", "attempt_count": 1, "failure_class": "authentication", "last_error_code": "string", "retry_disposition": "authentication_required", "circuit_state": "closed", "retry_not_before": "2019-08-24T14:15:22Z" }, "tool_outcome_blocker": { "blocker_id": "string", "reason": "tool.outcome_uncertain", "retry_not_before": "2019-08-24T14:15:22Z", "review": { "schema_version": 1, "review_core": { "schema_version": 1, "action_label": "string", "target_summary": "string", "attempted_at": "2019-08-24T14:15:22Z", "attempt_count": 1, "failure_class": "authentication", "error_code": "string", "uncertainty_reason": "string", "evidence": [ { "kind": "string", "label": "string", "content_digest": "stringstringstringstringstringstringstringstringstringstringstringstrin" } ] }, "attestable": true, "review_digest": "string", "evidence_links": [ { "kind": "tool_call_audit", "label": "string", "resource_id": "string" } ] }, "resolution_committed": false, "resume_pending": false, "resolution_id": "e25ae328-69b8-4e08-9f09-52d881051e39", "resolution": "abandon_operation" }, "tool_outcome_wake_state": "string", "tool_calls_count": 0, "tool_attempts_count": 0, "tokens_used": 0, "input_tokens": 0, "output_tokens": 0, "model": "string", "cost_usd": 0, "cost_pricing_fallback": true, "sandbox_duration_ms": 0, "sandbox_cost_cents": 0, "sandbox_id": "string", "desktop_stream_url": "string", "child_group_id": 1, "child_scope_key": "string", "child_scope_label": "string", "child_group_count": 0, "project_tag": "string", "ticket_tag": "string", "cost_center_tag": "string" }, "plan": { "enforcement_state": { "source": "string", "strict_action_index": 0, "current_strict_action": { "index": 0, "kind": "string", "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "allowed_inputs": [ "string" ], "success_signal": "string" }, "remaining_strict_actions": [ { "index": 0, "kind": "string", "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "allowed_inputs": [ "string" ], "success_signal": "string" } ], "completed_strict_actions": 0, "adaptive_step_index": 0, "active_adaptive_step": { "index": 0, "title": "string", "intent": "string", "expected_activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" } ], "success_signal": "string" }, "remaining_adaptive_steps": [ { "index": 0, "title": "string", "intent": "string", "expected_activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" } ], "success_signal": "string" } ], "completed_adaptive_steps": 0, "last_progress_at": "string", "is_stalled": false, "latest_warning_type": "string" }, "plan": { "id": 0, "run_id": 1, "version": 1, "planning_mode": "adaptive", "status": "active", "goal": "string", "done_checks": [ "string" ], "risk_summary": { "risk_mode": "high", "allowed_capabilities": [ "artifact_write" ], "execution_environment": "guest_vm", "privileged_capabilities": [ "artifact_write" ], "requires_approval": true }, "expected_activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" } ], "actions": [ { "index": 0, "kind": "string", "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "allowed_inputs": [ "string" ], "success_signal": "string" } ], "steps": [ { "index": 0, "title": "string", "intent": "string", "expected_activities": [ { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" } ], "success_signal": "string" } ], "approved_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z" }, "replan_fence": { "expected_policy_version": 1, "expected_replay_generation": 1 } }, "semantic_progress": { "revision": 1, "reason": "admission", "updated_at": "2019-08-24T14:15:22Z", "projection_health": "complete", "degradation_code": "enrichment_capacity_exceeded", "objective": "string", "objective_truncated": true, "plan_version": 1, "platform_completed": [ { "id": "string", "summary": "string", "completed_at": "2019-08-24T14:15:22Z", "plan_version": 0 } ], "platform_completed_total": 0, "platform_current_step": { "id": "string", "summary": "string", "plan_index": 0 }, "platform_next_steps": [ { "id": "string", "summary": "string", "plan_index": 0 } ], "platform_next_steps_total": 0, "agent_completed_claims": [ { "id": "string", "summary": "string", "completed_at": "2019-08-24T14:15:22Z", "plan_version": 0 } ], "agent_completed_claims_total": 0, "agent_current_focus": { "id": "string", "summary": "string", "plan_index": 0 }, "agent_proposed_next_steps": [ { "id": "string", "summary": "string", "plan_index": 0 } ], "agent_proposed_next_steps_total": 0, "blockers": [ { "id": "string", "code": "string", "summary": "string", "first_seen_at": "2019-08-24T14:15:22Z", "retryable": true } ], "blockers_total": 0, "open_questions": [ { "id": "string", "summary": "string", "first_seen_at": "2019-08-24T14:15:22Z", "correlation_id": "string" } ], "open_questions_total": 0, "artifacts": [ { "artifact_id": "b7bd6bbb-c7f1-4314-8742-2aeeeece9d12", "file_name": "string", "status": "deleted", "is_primary": true } ], "artifacts_total": 0, "verification_status": "not_evaluated", "verification_checks_passed": 0, "verification_checks_total": 0, "verification_evaluated_at": "2019-08-24T14:15:22Z" }, "child_groups": { "groups": [ { "id": 1, "label": "string", "status": "cancelled", "strategy": "manual_batch", "verification_status": "pending_verification", "expected_children": 0, "total_child_runs": 0, "completed_children": 0, "failed_children": 0, "cancelled_children": 0, "aggregate_tool_calls": 0, "aggregate_tokens_used": 0, "children": [ { "run_id": 1, "scope_key": "string", "scope_label": "string", "status": "awaiting_plan_approval" } ], "children_truncated": true, "created_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z" } ], "total": 0, "truncated": true }, "tool_activity": { "recent_calls": [ { "id": 0, "run_id": 0, "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "root_run_id": 0, "call_depth": 0, "action": { "kind": "domain_tool", "domain_tool": { "origin": "builtin", "source_id": "string", "canonical_name": "string", "display_name": "string", "enabled": true, "owned_by_caller": true }, "title": "string", "summary": "string" }, "success": true, "error_message": "string", "interrupted": true, "interruption_type": "string", "interruption_message": "string", "pause_status": "string", "started_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "duration_ms": 0 } ], "total": 0, "truncated": true }}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}{ "detail": "string", "error_code": "string", "request_id": "string"}