Run an agent
/api/v1/agents/{agent_id}/runStart an execution of this agent.
Admission is synchronous and execution is not. A successful call answers 202 with the admitted run, and the run row is the pointer for polling and for the event stream. Limit and budget rejections surface on this call with their own status codes, so a 202 means the run was both authorized and affordable.
An optional Idempotency-Key header makes the start retry-safe: re-presenting the same key returns the run already admitted rather than admitting — and charging for — a second one. The key is scoped to the caller and this agent, and a replay must carry the original payload; reusing a key with different input is rejected with 409.
If the agent defines output_schema, platform verification runs only after a successful, non-paused terminal result. The response must be one exact finite JSON object, with no prose or code fence. After secret redaction and control-character sanitization, that exact persisted object is validated against the platform's bounded JSON Schema Draft 2020-12 profile. References must be local and begin with #; schema validation does not coerce values or insert defaults.
A schema match completes with verification_status=verified. A mismatch changes the execution to failed and records verification_failed. If execution fails or pauses before the verifier runs, verification remains not_evaluated; a successful run with no applicable verifier completes as unverified.
Required access
Credentials: service principal, delegated token, user session
Scope: agents:invoke
The agent must be shared with the organization, or granted to the calling principal if it is restricted.
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
uuidHeader 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 executing an agent.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/run" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Idempotency-Key: 9f8c2b7a-1d3e-4f5a-8b6c-2e1d0a9f8c7b" \ -H "Content-Type: application/json" \ -d '{ "input_data": { "repository": "acme/checkout", "since": "2026-07-01" }, "message": "Summarize the release-blocking issues.", "project_tag": "checkout-rewrite" }'{ "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" }}{ "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"}{ "detail": "string", "error_code": "string", "request_id": "string"}