Read a file from a controlled run sandbox
/api/v1/runs/{run_id}/sandbox/control/{control_id}/files/readSubmit an asynchronous whole-file UTF-8 read from the controlled run sandbox, then poll the returned operation.
Relative paths resolve from /home/user; absolute paths remain inside the run's guest machine and may address locations such as /tmp. Content is capped at 5 MiB. Binary, invalid UTF-8, or oversized files fail without returning partial data.
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:read
The exact credential that owns this active control may read files.
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.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
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/files/read" \ -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "request_id": "6184e61e-7635-457d-b801-b256101639a8", "path": "reports/result.json" }'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "run_id": 0, "control_id": "81e20d46-f0a2-4692-a3cd-ac0ccfe84ea6", "sequence": 0, "request_id": "266ea41d-adf5-480b-af50-15b940c2b846", "kind": "command", "status": "cancelled", "failure_code": "string", "created_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z"}Run a command in a controlled run sandbox POST
Submit one size-limited command to the controlled run sandbox. Execution is asynchronous; poll the returned operation for the result.
Write a file in a controlled run sandbox POST
Submit an asynchronous whole-file UTF-8 write inside the controlled run sandbox, then poll the returned operation.