API referenceTeams
Retrieve a workforce run
GET
/api/v1/workforce-runs/{run_id}Retrieve the parent run together with its child groups, partial and merged output, coordination data, and workforce verification result.
workforce_run.verification explains the workforce policy mode and its detailed result. pending_verification means the policy was not evaluated; unverified means no applicable policy, schema, or child output was available; verified means the configured deterministic policy passed; and verification_failed means it failed.
workforce_run.run.verification_status is the cross-run aggregate. A workforce policy failure normally pairs verification_failed with execution status paused_for_replan; a pause before any verification ran pairs with not_evaluated. Inspect both execution and verification status.
Required access
Credentials: service principal, delegated token, user session
Scope: teams:read
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/workforce-runs/0" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"{ "workforce_run": { "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, "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": "concurrency.global", "scope": "global", "message": "string", "scope_id": "string", "limit": 0, "actual": 0, "retry_after_seconds": 0 }, "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_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" }, "team_id": "810007d0-bec5-486c-b5d1-28fcd8a079ba", "orchestration_profile": "map_reduce", "await_mode": "async", "child_groups": [ { "id": 1, "parent_run_id": 1, "label": "string", "status": "cancelled", "strategy": "manual_batch", "verification_status": "pending_verification", "expected_children": 0, "max_failed_children": 0, "completed_children": 0, "failed_children": 0, "cancelled_children": 0, "total_child_runs": 0, "aggregate_tool_calls": 0, "aggregate_tokens_used": 0, "aggregate_interruption_count": 0, "items": [ { "id": 1, "group_id": 1, "child_run_id": 1, "scope_key": "string", "scope_label": "string", "status_snapshot": "awaiting_plan_approval", "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z" } ], "scope_leases": [ { "id": 1, "parent_run_id": 1, "scope_key": "string", "scope_label": "string", "owner_run_id": 1, "assigned_agent_id": "86914e44-3b25-4323-af2e-e5bb50c313f0", "status": "completed", "attempt_count": 0, "denial_count": 0, "lease_expires_at": "2019-08-24T14:15:22Z", "last_heartbeat_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "metadata": { "task_metadata": { "property1": null, "property2": null } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "output": { "property1": null, "property2": null }, "partial_results": { "property1": null, "property2": null }, "task_manifest": { "version": 1, "summary": "string", "items": [ { "scope_key": "string", "scope_label": "string", "task_description": "string", "acceptance_criteria": [ "string" ], "input_data": { "property1": null, "property2": null }, "priority": 0, "estimated_complexity": "string" } ], "global_context": { "property1": null, "property2": null }, "planner_run_id": 1, "created_at": "2019-08-24T14:15:22Z" }, "checklist": { "version": 1, "items": [ { "id": "string", "label": "string", "status": "blocked", "verified_at": "2019-08-24T14:15:22Z", "verified_by": "string", "notes": "string" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }, "verification": { "status": "pending_verification", "mode": "none", "message": "string", "details": { "child_count": 0, "failed_run_ids": [ 0 ], "error_count": 0, "errors": [ { "path": [ "string" ], "message": "string", "type": "string" } ], "schema_sha256": "string", "output_sha256": "string", "output_sha256_by_run_id": { "property1": "string", "property2": "string" }, "schema_dialect": "string", "schema_validator": "string", "schema_validator_version": "string" } }, "coordination_metrics": { "total_scopes": 0, "completed_scopes": 0, "leased_scopes": 0, "expired_scopes": 0, "conflict_count": 0, "useful_work_rate": 0, "duplicate_work_rate": 0, "idle_child_rate": 0, "conflict_rate": 0, "verification_failure_rate": 0, "replan_count": 0, "straggler_rate": 0, "aggregate_tokens_used": 0, "aggregate_tool_calls": 0, "aggregate_interruption_count": 0, "concurrent_write_conflicts": 0, "rewrite_conflicts": 0, "temporal_conflicts": 0 }, "recommendations": [ { "code": "string", "message": "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"}{ "detail": "string", "error_code": "string", "request_id": "string"}