> ## Documentation Index > Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get a sandbox by id > Retrieve a sandbox by id, with its status, size, host, exposed ports and timers. GET /sandboxes/{id} in the Ravion API reference. ## OpenAPI ````yaml https://api.ravion.com/openapi.yaml get /sandboxes/{id} openapi: 3.0.0 info: title: Ravion version: 0.0.0 servers: - url: https://api.ravion.com security: - BearerAuth: [] tags: - name: Projects - name: Environments - name: FeatureFlags - name: Pipelines - name: PipelineRuns - name: TerraformResources - name: TerraformExecutionSummaries - name: PipelineStepExecutions - name: AwsCloudWatch - name: AwsAmp - name: PipelineVersions - name: Organizations - name: Stacks - name: StackWorkspaces - name: Auth - name: OAuth - name: User - name: Health - name: Memberships - name: ServiceAccounts - name: Integrations - name: AwsDefaultNetworks - name: AwsAccounts - name: ApiKeys - name: EksPrometheus - name: EksLoki - name: ExecutionEnvironments - name: ModuleDefinitions - name: ModuleCategories - name: ModuleVersions - name: ModuleInstances - name: DefaultValueDefinitions - name: DefaultValues - name: CodeSources - name: Github - name: GitHub Actions - name: Alerts - name: Gitlab - name: Slack - name: Git - name: MergeQueues - name: Values - name: Deployments - name: DeploymentResources - name: InfrastructureEvents - name: WebSocket - name: Domains - name: AcmCertificates - name: NotificationDestinations - name: NotificationDispatches - name: NotificationEvents - name: NotificationRules - name: Activity - name: Describe - name: Reports - name: BillingPlans - name: BillingAccounts - name: BillingCycles - name: BillingUsageSummaries - name: BillingAddOns - name: BillingInvoices - name: Authorization - name: Sandboxes - name: SandboxCommands - name: SandboxPorts - name: Apps paths: /sandboxes/{id}: get: tags: - Sandboxes summary: Get a sandbox by id description: >- Retrieve a sandbox by id, with its status, size, host, exposed ports and timers. operationId: GetSandbox parameters: - in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/Sandbox' required: - data type: object description: The request has succeeded. '400': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request is invalid or malformed. '401': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You are not authenticated '403': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You do not have permission to access this resource. '404': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The server cannot find the requested resource. '500': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Server error components: schemas: Sandbox: additionalProperties: false description: 'A sandbox: a development microVM you run commands in.' properties: app: allOf: - $ref: '#/components/schemas/SandboxAppRef' description: >- The app the sandbox runs. Set when the sandbox is an app's microVM, which the app creates; absent for a sandbox you created. readOnly: true cpu: description: vCPUs the sandbox has. format: int32 readOnly: true type: integer createdAt: allOf: - $ref: '#/components/schemas/UtcDateTime' readOnly: true diskGib: description: Disk the sandbox has, in GiB. format: int32 readOnly: true type: integer envKeys: description: >- Names of the environment variables set for every command. Their values are never returned. items: type: string readOnly: true type: array executionEnvironmentId: description: Execution environment (`ee_*`) whose sandbox pool runs the sandbox. readOnly: true type: string expiresAt: allOf: - $ref: '#/components/schemas/UtcDateTime' description: When a paused or stopped sandbox expires. Absent while it runs. readOnly: true host: allOf: - $ref: '#/components/schemas/SandboxHostRef' description: The host the sandbox runs on. Absent while it is not running. readOnly: true id: readOnly: true type: string idleTimeoutSeconds: description: >- Seconds without a running command or an open connection to an exposed port before the sandbox is paused. `0` means it is never paused for being idle. format: int32 readOnly: true type: integer lastActiveAt: allOf: - $ref: '#/components/schemas/UtcDateTime' description: >- When a command last ran or a connection to an exposed port was last open. The idle timeout counts from here. readOnly: true memoryMib: description: Memory the sandbox has, in MiB. format: int32 readOnly: true type: integer moduleInstanceId: description: >- Module instance the sandbox belongs to. Set when the sandbox was created for one; it is what lets the sandbox expose ports on the module's managed domains and push images to the module's registry. readOnly: true type: string onResume: description: >- Command run inside the sandbox after every resume, as argv. Use it to bring a dev server back after a pause. It runs as the command `onresume`, whose status and output you can read like any other command's. items: type: string readOnly: true type: array organizationId: readOnly: true type: string pausedAt: allOf: - $ref: '#/components/schemas/UtcDateTime' description: When the sandbox was paused or stopped. Absent while it runs. readOnly: true ports: description: Ports exposed on managed domains. items: $ref: '#/components/schemas/SandboxPort' readOnly: true type: array retentionSeconds: description: >- Seconds a paused or stopped sandbox is kept before it expires and its snapshot is deleted. format: int32 readOnly: true type: integer status: allOf: - $ref: '#/components/schemas/Sandbox.Status' description: Where the sandbox is in its life. readOnly: true statusReason: description: >- Why the sandbox is `STOPPED` or `FAILED`: `host_lost`, `interrupted`, or the error that stopped it from starting. readOnly: true type: string updatedAt: allOf: - $ref: '#/components/schemas/UtcDateTime' readOnly: true required: - id - createdAt - updatedAt - organizationId - executionEnvironmentId - status - cpu - memoryMib - diskGib - idleTimeoutSeconds - retentionSeconds - envKeys - ports type: object Errors.UserFacingErrorData: additionalProperties: false description: |- User-facing error presentation data. This is what the API returns to the frontend after formatting ErrorData using CEL templates from the error registry. Used for both: - Error fields on domain models (e.g., PipelineRun.error) - API error response bodies (HTTP 4xx/5xx responses) properties: action: allOf: - $ref: '#/components/schemas/Errors.Action' description: Optional action to help resolve the error code: description: Full error code, e.g., "Ravion:Pipeline:NOT_FOUND" type: string description: description: Additional description with more details type: string details: description: Structured details rendered as user-facing sections. items: $ref: '#/components/schemas/Errors.UserFacingErrorDetailSection' type: array isInternal: description: >- Indicates whether this error is internal (only set when ShowInternal=true). This allows SUPERADMINs to identify internal errors while viewing full details. type: boolean message: description: Main error message (required) type: string metadata: additionalProperties: {} description: >- Error params/metadata. Stripped for internal errors unless superadmin. type: object requestId: description: Request ID for correlating errors with server logs. type: string required: - code - message type: object SandboxAppRef: additionalProperties: false description: The app a sandbox runs, for a sandbox that is an app's microVM. properties: appId: description: >- App (`sapp_*`) the sandbox runs. Deploy, pause, resume and delete it through the app. type: string branch: description: >- Branch the app's last deploy was made from. Absent until the app is first deployed, and when the files were not on a branch. type: string commit: description: >- Commit of the files the app's last deploy uploaded. Absent until the app is first deployed, and for files that were not taken from a git commit. type: string moduleInstanceId: description: >- App Cluster module instance (`minst_*`) the app is deployed onto. Its sandbox pool runs the sandbox and its router serves the app's URLs. type: string required: - appId - moduleInstanceId type: object UtcDateTime: description: UTC RFC3339 timestamp with a required Z suffix format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ type: string x-go-type: apitypes.UTCDateTime x-go-type-import: name: apitypes path: ravion/api-go/pkg/apitypes SandboxHostRef: additionalProperties: false description: The host a sandbox runs on. properties: hostId: description: >- Host id, which is the EC2 instance the host runs on in your sandbox pool. type: string since: allOf: - $ref: '#/components/schemas/UtcDateTime' description: When the sandbox was placed on this host. required: - hostId - since type: object SandboxPort: additionalProperties: false description: A sandbox port exposed on one of your managed domains. properties: domain: description: Fully-qualified domain name the port is served on. type: string error: description: Why the route could not be set up, when `status` is `ERROR`. type: string port: description: Port the sandbox listens on. format: int32 maximum: 65535 minimum: 1 type: integer status: allOf: - $ref: '#/components/schemas/Sandbox.PortStatus' description: Whether traffic reaches the port yet. takeover: description: >- True when the domain was taken over from the module instance that normally serves it. Closing the port gives the domain back. type: boolean url: description: URL that reaches the port, always `https://`. type: string required: - port - domain - url - status - takeover type: object Sandbox.Status: description: >- Where a sandbox is in its life. `PENDING`: created, waiting for a host. `STARTING`: a host is booting it. `RUNNING`: ready for commands. `PAUSING`: its disk is being snapshotted. `PAUSED`: stopped with a snapshot to resume from. `RESUMING`: booting from its snapshot. `STOPPING`/`STOPPED`: stopped by you or by the loss of its host; a stopped sandbox with a snapshot can be resumed. `EXPIRED`: its retention period ended and its snapshot was deleted. `DELETED`: deleted on request. `FAILED`: it could not be started; see `statusReason`. enum: - PENDING - STARTING - RUNNING - PAUSING - PAUSED - RESUMING - STOPPING - STOPPED - EXPIRED - DELETED - FAILED type: string Errors.Action: additionalProperties: false description: Action to help user resolve the error properties: label: description: Button/link label text type: string url: description: URL to navigate to for resolution type: string required: - label - url type: object Errors.UserFacingErrorDetailSection: additionalProperties: false description: Structured user-facing error detail section. properties: items: description: List of detail values for this section. items: type: string type: array object: additionalProperties: {} description: Structured detail payload for object rendering. type: object render: description: Rendering hint for clients. Valid values are list or object. type: string title: description: Detail section title shown in the UI. type: string required: - title - render type: object Sandbox.PortStatus: description: >- Whether traffic reaches an exposed port. `PENDING`: the route is being set up. `ACTIVE`: the URL serves the sandbox. `ERROR`: the route could not be set up; see `error`. enum: - PENDING - ACTIVE - ERROR type: string securitySchemes: BearerAuth: scheme: Bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.