> ## Documentation Index > Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a sandbox execution ## OpenAPI ````yaml /api-spec/sandbox_api.yaml get /executions/{execution_id} openapi: 3.0.3 info: title: GMI Sandbox API description: >- REST API for GMI Sandbox: create isolated execution environments from templates, manage their lifecycle on the control plane, and run commands or transfer files through each sandbox's own data plane. contact: name: GMI Cloud Support email: support@gmicloud.ai version: '2.0' servers: - url: https://console.gmicloud.ai/api/v2 description: Control plane security: - bearerAuth: [] tags: - name: Sandbox description: | Sandbox instance lifecycle management (Sandbox v2, /api/v2/sandboxes) - name: SandboxTemplate description: Sandbox template management (Sandbox v2, `/api/v2/templates`) - name: Sandbox-Exec description: > Sandbox execution data plane (accessed via the sandbox host and sandbox access token). These endpoints are not under the control plane's `/api/v2` path; clients connect directly to `https://{sandbox_key}.{domain}` and authenticate with `X-Access-Token`. - name: Sandbox-Files description: > Sandbox file data plane (`/files`). **These endpoints are not under `/api/v2`** and do not use `Authorization: Bearer`: they are served by the sandbox's own data-plane entry point — clients connect directly to `https://{sandbox_key}.{domain}` and authenticate with `X-Access-Token`. `{sandbox_key}` is the `sandbox_key` returned by the create/connect endpoints, used for data-plane host addressing. `{domain}` and `X-Access-Token` are the `domain` and `sandbox_access_token` from the same responses — no extra endpoint is needed to obtain them. This split is not historical baggage but the nature of a data plane: file transfer is long-lived, high-volume, and addressed per sandbox, differing from the control plane's short requests in both capacity model and failure domain, so they do not share an entry point. **One unified abstraction.** The same contract is served by two backend kinds (an in-sandbox file service / a data-center data-plane proxy); clients need not — and cannot — tell them apart. The cost is that the contract is their intersection: `Content-Length` on download and resumable download (`Range`/`206`) are **optional capabilities** that vary by data center, and clients must work correctly when they are absent. See the per-operation notes below. paths: /executions/{execution_id}: servers: - url: https://{sandbox_key}.{domain} description: > Sandbox data-plane entry point. Both variables come from the create/connect response: `sandbox_key` is `data.sandbox_key`, `domain` is `data.domain`. variables: sandbox_key: default: sandbox-key description: >- Sandbox key (the `sandbox_key` returned by the create/connect endpoints) domain: default: sandbox.example.com description: > The `domain` returned verbatim by the create/connect endpoints. Its default naming shape is `{idc-name}.{root-hostname}`, but clients must not assemble or derive it themselves. get: tags: - Sandbox-Exec summary: Get a sandbox execution operationId: getSandboxExecution parameters: - $ref: '#/components/parameters/SandboxExecExecutionIDParam' - $ref: '#/components/parameters/SandboxExecRequestIDParam' responses: '200': description: Current execution status and any available output. content: application/json: schema: $ref: '#/components/schemas/SandboxExecResultResponse' '400': $ref: '#/components/responses/SandboxExecBadRequest' '401': $ref: '#/components/responses/SandboxExecUnauthorized' '404': $ref: '#/components/responses/SandboxExecNotFound' '429': $ref: '#/components/responses/SandboxExecRateLimited' '500': $ref: '#/components/responses/SandboxExecInternalError' security: - sandboxAccessToken: [] servers: - url: https://{sandbox_key}.{domain} description: Sandbox data-plane host variables: sandbox_key: default: sandbox-key description: >- Data-plane addressing key (`sandbox_key` from the control-plane response). domain: default: sandbox.example.com description: Sandbox data-plane domain from the control-plane response. components: parameters: SandboxExecExecutionIDParam: name: execution_id in: path required: true description: Public execution identifier returned by the create operation. schema: type: string format: uuid SandboxExecRequestIDParam: name: X-Request-ID in: header required: false description: Optional request correlation identifier echoed in the response. schema: type: string minLength: 1 maxLength: 128 schemas: SandboxExecResultResponse: type: object required: - execution_id - sandbox_id - status - exit_code - stdout - stderr - stdout_truncated - stderr_truncated - started_at - completed_at properties: request_id: type: string description: Echo of X-Request-ID when supplied. execution_id: type: string format: uuid sandbox_id: type: string description: >- Echo of the data-plane addressing key (i.e. `sandbox_key`; the data plane identifies the instance by the key in the host). status: $ref: '#/components/schemas/SandboxExecStatus' exit_code: type: integer format: int32 nullable: true description: Process exit code; null while non-terminal or when canceled. stdout: type: string nullable: true description: Captured standard output, or null while not yet available. stderr: type: string nullable: true description: Captured standard error, or null while not yet available. stdout_truncated: type: boolean nullable: true stderr_truncated: type: boolean nullable: true started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true SandboxExecStatus: type: string description: Public lifecycle status of a sandbox execution. enum: - pending - running - canceling - succeeded - failed - canceled SandboxExecErrorResponse: type: object required: - code - message properties: code: type: string description: Machine-readable execution error code. example: Execution.InvalidRequest message: type: string description: Sanitized human-readable error message. request_id: type: string description: Request correlation identifier. details: type: object additionalProperties: true responses: SandboxExecBadRequest: description: Invalid execution request or query parameter. content: application/json: schema: $ref: '#/components/schemas/SandboxExecErrorResponse' SandboxExecUnauthorized: description: Missing or invalid X-Access-Token. content: application/json: schema: $ref: '#/components/schemas/SandboxExecErrorResponse' SandboxExecNotFound: description: Execution does not exist or is not owned by this sandbox. content: application/json: schema: $ref: '#/components/schemas/SandboxExecErrorResponse' SandboxExecRateLimited: description: The execution provider rate-limited the request. content: application/json: schema: $ref: '#/components/schemas/SandboxExecErrorResponse' SandboxExecInternalError: description: The execution provider or proxy failed to complete the request. content: application/json: schema: $ref: '#/components/schemas/SandboxExecErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer description: > API Key or Access Token, always sent as `Authorization: Bearer `. The gateway recognizes the token type automatically. sandboxAccessToken: type: apiKey in: header name: X-Access-Token description: > Sandbox data-plane token — the `sandbox_access_token` returned by the create/connect endpoints. Used for `/files`, Sandbox-Exec, and other data-plane endpoints; the control plane (`/api/v2`) does not accept it, and conversely the control plane's `Authorization: Bearer` is invalid on the data plane. The token is bound to its sandbox: using sandbox A's token against sandbox B's host fails. It stays valid until the sandbox's lifetime ends; there is no separate rotation endpoint (`rotate_traffic_token` rotates the port traffic token `traffic_access_token` and does not affect this one). ````