Start a workforce run
/api/v1/workforce-runsStart a team execution and return its composed workforce projection.
An optional Idempotency-Key header makes admission retry-safe. The key is scoped to the caller and team; replay it only with the original request body. Reusing it with different input is rejected with 409.
The effective verification policy is frozen for each execution attempt and evaluated after child work is assembled. none records an unverified result; all_children_success checks child lifecycle outcomes; child_output_schema validates each selected child output; and team_output_schema validates the final merged output.
Both schema modes use the platform's bounded JSON Schema Draft 2020-12 profile. Schemas must describe a root object and may use only local references beginning with #; validation uses the persisted JSON objects without coercion or default insertion.
A policy mismatch records verification_failed and parks the parent run as paused_for_replan. If orchestration stops before the verifier can run, verification stays not_evaluated. A run that completes without an applicable check is unverified.
Required access
Credentials: service principal, delegated token, user session
Scope: teams:invoke
Runs started with a service-principal key have no acting user. They are attributed to the key itself, and member agents fall back to their owner for anything user-scoped (agent memory, prompt context). A member that reaches ask_user or send_email in such a run gets a tool error rather than a hang — use a delegated token if the team depends on either.
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
Header Parameters
Makes this start retry-safe. Generate one stable value per intended execution and reuse it only when retrying that same execution: the key is scoped to the caller and the target resource, and re-presenting it returns the run already admitted instead of starting a second one. A replay must carry the original payload — the same key with different input answers 409.
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.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Request body for starting a workforce run.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/workforce-runs" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Idempotency-Key: 9f8c2b7a-1d3e-4f5a-8b6c-2e1d0a9f8c7b" \ -H "Content-Type: application/json" \ -d '{ "team_id": "6f1d6f9c-6a37-4d0a-9d9f-1a2b3c4d5e6f", "task": "Review the checkout rewrite and report blocking defects.", "await_mode": "async" }'{ "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"}{ "detail": "string", "error_code": "string", "request_id": "string"}