Guest Machines
API referenceRuns

List runs

GET/api/v1/runs

List runs in the organization, newest first.

Every execution the platform started appears here, whoever started it — the endpoint is scoped to the organization, not to the calling principal. The exception is a member's private run (their chats, and their runs of their own private agents), which only that member sees.

A workspace owner or admin signed in to the app also gets other members' private runs (their chats, and their runs of their own private agents), as rows with private: true that carry only status, timing, the agent and whose run it is, so they can be cancelled or deleted. API keys never receive these rows.

Filter by project_tag, ticket_tag, or cost_center_tag to retrieve exactly the runs one integration started — set those tags when you start the run and they stay attached through analytics and chargeback exports.

Pass root_only=true to exclude runs spawned by other runs. Without it, one delegated invocation can appear as several results.

Required access

Credentials: automation account, delegated token, user session, user API key

User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.

Scope: runs:list

Runs are organization-shared with no per-caller visibility axis, so enumeration is all-or-nothing and needs runs:list.

Authorization

AuthorizationBearer <token>

A user-owned key prefixed gsmc_uk_, bound to one organization. It follows its owner's current membership, role and resource permissions, optionally restricted to read-only access. No X-Org-Id header is needed; a conflicting organization is rejected. Credential creation, personal connection setup and human attestations require a signed-in session. Runs are private to the calling user; sharing an agent grants access to your own personal memory of it, never to the agent's own memory.

In: header

Query Parameters

agent_id?|

Filter by agent ID

workflow_id?|

Filter to runs of this workflow

status?|

Filter by status

error_category?|

Filter by error category

root_only?Root Only

Only show root runs (call_depth=0)

Defaultfalse
waiting_on_person?Waiting On Person

Only runs waiting for an approval, answer, or limit change

Defaultfalse
project_tag?|

Filter by project tag

ticket_tag?|

Filter by ticket tag

cost_center_tag?|

Filter by cost center tag

limit?Limit
Range1 <= value <= 100
Default50
offset?Offset
Range0 <= value
Default0

Header Parameters

X-Org-Id?|

Selects the active organization for a direct user session that has more than one membership. Automation account keys and delegated tokens are each bound to one organization and ignore it.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/runs" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"
{  "runs": [    {      "id": 1,      "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978",      "invocable_type": "agent",      "workflow_id": "03e70e31-d7a4-4401-a629-6a4b6096cdfe",      "enclosing_workflow_run_id": 1,      "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",      "queued_since": "2019-08-24T14:15:22Z",      "last_action": {        "action": "answered",        "at": "2019-08-24T14:15:22Z",        "by_principal_type": "agent",        "by_name": "string",        "by_run_starter": true      },      "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,      "pause_reason": {        "category": "manual",        "code": "string",        "message": "string"      },      "limit_detail": {        "error": "limit_exceeded",        "limit_type": "account.needs_approval",        "scope": "agent",        "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_outcome_resume_retryable": false,      "tool_calls_count": 0,      "tool_attempts_count": 0,      "tokens_used": 0,      "input_tokens": 0,      "output_tokens": 0,      "cache_read_input_tokens": 0,      "cache_creation_input_tokens": 0,      "platform_model_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"    }  ],  "total": 0,  "total_cost_usd": 0,  "status_counts": {    "property1": 0,    "property2": 0  },  "attention_count": 0}

Rerun a workflow run from a step POST

Repeat a failed or cancelled workflow run from one of its steps. The new run reuses the results of the steps before `from_step` and runs the rest again, as the caller. It uses the revision the original run used unless `use_latest_revision` is set.

Retrieve a run GET

Retrieve a run the caller may access.