> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get suspension
> Read a computer’s status and its current suspension.
Returns a computer's status and its current suspension: whether its memory is still being saved, where it lives, and how far a copy has got. Poll it after a [suspend](/api-reference/computers/suspend) or [resume](/api-reference/computers/resume) that returned `202`, until `status` reads `suspended` or `running`. Anyone who can see the computer can read it.
## Path parameters
Computer UUID or `instance_id`. Both resolve to the same computer.
## Query parameters
`resume` asks Orgo to check a `running` computer against its host once more after a resume, so its connection details are up to date.
## Response
Computer identifier (UUID).
The computer's status, as [Get computer](/api-reference/computers/get) reports it. While it is `suspending` or `resuming`, each read also checks its host, so a finished save or resume shows here.
The computer's current or most recent suspension. `null` when none is recorded.
`capturing`, `uploading`, `stored`, `resuming`, `resumed`, `failed`, or `abandoned`.
`ram` (memory and disk saved) or `disk_only`.
Bytes saved so far.
Bytes to save.
From `0` to `1`. `1` once the copy is stored. `null` when the size is not known yet.
`true` when saving the copy failed and the computer's memory is kept on its host only. It can still be resumed there.
`true` when `state` is `failed`.
`host` or `storage`. A computer in storage has left its host and wakes on Resume or Start.
`true` while the copy is still being saved to storage. The computer can be resumed or deleted meanwhile.
The storage region of the copy, or `null`.
ISO 8601 timestamp.
ISO 8601 timestamp.
ISO 8601 timestamp.
ISO 8601 timestamp.
ISO 8601 timestamp.
The computer's placement and connection record, without its credentials.
The computer's API address on its fleet host. See [Get computer](/api-reference/computers/get).
## Example
```bash cURL theme={null}
curl https://www.orgo.ai/api/computers/$COMPUTER_ID/suspension \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import requests
response = requests.get(
f"https://www.orgo.ai/api/computers/{computer_id}/suspension",
headers={"Authorization": f"Bearer {api_key}"}
)
data = response.json()
print(data["status"], data["suspension"])
```
```javascript JavaScript theme={null}
const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}/suspension`, {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const { status, suspension } = await response.json();
console.log(status, suspension);
```
### Response
```json theme={null}
{
"id": "a3bb189e-8bf9-3888-9912-ace4e6543002",
"status": "suspended",
"suspension": {
"state": "uploading",
"kind": "ram",
"bytes_done": 2147483648,
"bytes_total": 4294967296,
"progress": 0.5,
"local_only": false,
"failed": false,
"suspended_at": "2026-10-13T09:12:00.000Z",
"stored_at": null,
"resume_started_at": null,
"resumed_at": null,
"updated_at": "2026-10-13T09:12:40.000Z",
"where": "host",
"saving": true,
"region": "nyc"
},
"instance_details": {
"provider": "metal",
"id": "a3881618",
"resolution": "1280x720x24"
},
"url": "http://162.43.189.25:8231"
}
```
## Errors
| Status | Body | When |
| - | - | - |
| `401` | `{ "error": "Invalid API key" }` | The Bearer token starts with `sk_` but is not a known Orgo key. |
| `401` | `{ "error": "Authentication required" }` | No `Authorization` header, or a Bearer token that is not an `sk_` key. |
| `402` | `{ "error": "Choose a plan to continue." }` | The computer is a trial computer whose trial has ended. `error` is "Manage this computer’s payment in Account → Usage." when its payment is managed there. |
| `403` | `{ "error": "You do not have access to this workspace." }` | You are not a member of the computer's workspace. |
| `403` | `{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }` | The API key is scoped to a different workspace. |
| `404` | `{ "error": "Desktop not found" }` | No computer matches the id. |
| `500` | `{ "error": "Failed to read the computer’s suspension" }` | The read failed. |
| `503` | `{ "error": "Service temporarily unavailable. …" }` | Orgo could not verify the credential because of a server-side fault. The response carries `Retry-After: 5`. Retry after that delay. |
## OpenAPI
````yaml GET /computers/{id}/suspension
openapi: 3.1.0
info:
title: Orgo API
description: >-
Launch cloud computers that AI agents can control and interact with. Create
workspaces, provision computers, and control them programmatically.
version: 2.0.0
contact:
name: Orgo Support
email: spencer@orgo.ai
url: https://orgo.ai
servers:
- url: https://www.orgo.ai/api
description: Production
security:
- bearerAuth: []
tags:
- name: Account
description: >-
Account capacity: how many computers an account may run, and adding or
giving back more.
- name: Agent accounts
description: >-
Accounts an AI agent makes for itself, and the claim link a person uses to
take one over.
- name: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- name: Workspaces
description: Organize computers into named workspaces
- name: Computers
description: Provision and manage virtual computers
- name: Computer Lifecycle
description: Start, stop, and restart computers
- name: Computer Actions
description: Control mouse, keyboard, and execute commands
- name: Screens
description: >-
More than one desktop on a single computer. Each screen is its own X
server with its own cursor and window manager, so an agent working on one
cannot disturb another.
- name: Files
description: Upload and download files
- name: Templates
description: Author, build, and launch reproducible computers from templates
- name: Chat
description: Run an agent on a computer through OpenAI-compatible chat completions.
paths:
/computers/{id}/suspension:
get:
tags:
- Computer Lifecycle
summary: Get suspension
description: >-
Returns the computer's status and its current suspension: whether its
memory is still being saved (with progress), stored, or coming back.
Poll it after a `202` from suspend or resume. Each call while it is
`suspending` or `resuming` also settles the status from its host. Send
`?after=resume` to check a computer that just came back `running`.
operationId: getComputerSuspension
parameters:
- name: id
in: path
required: true
description: Computer UUID or instance_id
schema:
type: string
- name: after
in: query
required: false
description: >-
`resume`: also check a `running` computer that just resumed, so its
connection details are current.
schema:
type: string
enum:
- resume
responses:
'200':
description: The status and suspension.
content:
application/json:
schema:
type: object
properties:
id:
type: string
status:
type: string
description: The computer's status, as on `GET /computers/{id}`.
suspension:
oneOf:
- $ref: '#/components/schemas/Suspension'
- type: 'null'
description: The newest suspension, or `null` when none is recorded.
instance_details:
type:
- object
- 'null'
additionalProperties: true
description: The placement record, without credentials.
url:
type:
- string
- 'null'
example:
id: a3bb189e-8bf9-3888-9912-ace4e6543002
status: suspending
suspension:
state: uploading
kind: ram
bytes_done: 1073741824
bytes_total: 4294967296
progress: 0.25
local_only: false
failed: false
suspended_at: '2026-10-13T09:00:00.000Z'
stored_at: null
resume_started_at: null
resumed_at: null
updated_at: '2026-10-13T09:00:20.000Z'
where: host
saving: false
region: null
instance_details:
provider: metal
url: http://198.51.100.24:8081
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/TrialInactive'
'403':
$ref: '#/components/responses/AccessDeniedRead'
'404':
$ref: '#/components/responses/NotFound'
'500':
description: The suspension could not be read.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Failed to read the computer’s suspension
components:
schemas:
Suspension:
type: object
description: >-
A computer's suspension: where its memory is and how far saving it has
got. No host, bucket or key.
properties:
state:
type: string
enum:
- capturing
- uploading
- stored
- resuming
- resumed
- failed
- abandoned
kind:
type: string
enum:
- ram
- disk_only
bytes_done:
type:
- integer
- 'null'
bytes_total:
type:
- integer
- 'null'
progress:
type:
- number
- 'null'
description: 0 to 1 once the size is known (1 once stored), else `null`.
local_only:
type: boolean
description: >-
`true` when saving to storage failed and its host kept the memory:
it resumes only there.
failed:
type: boolean
suspended_at:
type:
- string
- 'null'
format: date-time
stored_at:
type:
- string
- 'null'
format: date-time
resume_started_at:
type:
- string
- 'null'
format: date-time
resumed_at:
type:
- string
- 'null'
format: date-time
updated_at:
type:
- string
- 'null'
format: date-time
where:
type: string
enum:
- host
- storage
saving:
type: boolean
description: '`true` while its storage copy is still being saved.'
region:
type:
- string
- 'null'
description: Region of its storage copy, such as `nyc`.
Error:
type: object
description: >-
The base error body. Every failure carries `error`; individual endpoints
add the fields named in the schemas below.
required:
- error
properties:
error:
type: string
description: Human-readable message.
example: Access denied
code:
type: string
description: >-
Machine-readable reason. Present on the failures that define one,
absent otherwise.
responses:
Unauthorized:
description: 'No usable credential. Send `Authorization: Bearer $ORGO_API_KEY`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
TrialInactive:
description: >-
The computer is a free trial computer whose trial is no longer active,
or it is paid for by its own subscription or dedicated purchase and that
payment has lapsed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
trial:
summary: Trial no longer active
value:
error: Choose a plan to continue.
payment:
summary: The computer's own payment has lapsed
value:
error: Manage this computer’s payment in Account → Usage.
AccessDeniedRead:
description: >-
You are not the owner or a member of the workspace, or the API key is
scoped to another workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
no-access:
summary: Not the owner or a member of the workspace
value:
error: You do not have access to this workspace.
scope-mismatch:
summary: The API key is scoped to another workspace
value:
error: >-
This API key cannot access this workspace
(workspace_scope_mismatch).
NotFound:
description: No computer with this id on your account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Desktop not found
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your key at orgo.ai/workspaces
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.