Keep programmatic sandbox control alive
/api/v1/runs/{run_id}/sandbox/control/{control_id}/heartbeatRecord continued use of an active control. Heartbeats do not bypass the control lifetime, run budgets, credential revocation, or sandbox limits.
Required access
Credentials: automation account, delegated token, 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:edit
The exact credential that acquired this active control may keep it alive.
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
Path Parameters
uuidHeader Parameters
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
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/runs/0/sandbox/control/497f6eca-6276-4993-bfeb-53cbbbba6f08/heartbeat" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY"{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "run_id": 0, "phase": "active", "release_requested": true, "requested_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "last_interaction_at": "2019-08-24T14:15:22Z", "ended_at": "2019-08-24T14:15:22Z"}Retrieve programmatic sandbox control GET
Poll a programmatic sandbox control while it moves through requested, active, and ended phases. `release_requested` reports an accepted release request before the control ends.
Release programmatic sandbox control POST
Request release of a programmatic control and hand the run-owned sandbox back to the agent. Poll the control until it ends.