> ## 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.
# Wait
> Pause on the computer for a fixed number of seconds before the next action.
Pauses on the computer for the given duration. The request blocks until the wait completes, so the round trip is at least as long as the pause you asked for.
## Path parameters
Computer ID (UUID). An `instance_id` is not accepted here and fails with `500`.
## Body parameters
How long to pause, in seconds. Must be greater than `0` and no more than `60`.
Fractional values are allowed. Omitting it is the same as sending `0` and
returns `400`. There is no default.
Deprecated alias for `seconds`, accepted for backwards compatibility. It is
read only when `seconds` is absent; if you send both, `seconds` wins and
`duration` is discarded. Same range and same validation.
Windows computers do not support `wait`. Their agent has no wait endpoint, so
the request returns `404` with `upstream_status: 404`. Pause on your side
instead.
`wait` takes no `?screen=` parameter. Unlike the pointer and keyboard actions,
sending one here is silently ignored rather than rejected. The pause is not
tied to a screen.
## Response
Always `true` on a `200`.
Always `wait`.
Carries `seconds`, an echo of the duration that was waited.
## Example
```bash cURL theme={null}
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/wait \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"seconds": 2.0}'
```
```python Python theme={null}
import requests
# Wait 2 seconds
requests.post(
f"https://www.orgo.ai/api/computers/{computer_id}/wait",
headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
json={"seconds": 2.0}
)
```
```javascript JavaScript theme={null}
// Wait 2 seconds
await fetch(`https://www.orgo.ai/api/computers/${computerId}/wait`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ seconds: 2.0 })
});
```
### Response
```json theme={null}
{
"success": true,
"action": "wait",
"details": { "seconds": 2 },
"error": null,
"error_type": null
}
```
Use waits sparingly. Prefer polling for the condition you actually care about, such as window focus or a file change, over fixed delays.
## Errors
| Status | Meaning |
| - | - |
| `400` | `seconds` is missing, `0`, or negative: `{"error": "wait duration must be positive"}`. Over 60 seconds returns `{"error": "wait duration 1m5s exceeds maximum of 1m0s"}`. Also returned when the computer has no VM attached (`{"error": "Desktop instance not available"}`), and by the computer agent when a body field has the wrong JSON type, such as `seconds` sent as a string rather than a number. |
| `401` | Invalid API key: `{"error": "Invalid API key"}`. A request with no `Authorization` header returns `{"error": "Authentication required"}`. Access failures also return `401` on this endpoint, not `403`: `{"error": "You do not have access to this workspace."}` when you are neither the owner nor a member of the computer's workspace, `{"error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)."}` for a view-only member, and `{"error": "This API key cannot access this workspace (workspace_scope_mismatch)."}` for a workspace-scoped key used outside its workspace. A server-side fault while verifying the credential also returns `401` here, with `{"error": "Service temporarily unavailable. …"}`. Retry that one; the key is fine. |
| `402` | The computer was created as a free trial that is no longer active: `{"error": "Choose a plan to continue."}`. |
| `404` | No computer with this id: `{"error": "Desktop not found"}`. A Windows computer also returns `404` for every wait, with `upstream_status: 404`. |
| `500` | The request body is not valid JSON, or the request failed for a reason the API could not classify. |
| `503` | The computer could not be reached: `{"error": "Could not reach the desktop. Try again in a moment.", "code": "ECONNREFUSED"}`. Safe to retry. A computer that never finished provisioning also returns `503`, with `{"error": "Computer not ready"}`. |
Every failure raised after the request leaves the API layer also carries a
`request_id`. Quote it in support requests. When the computer agent itself
answered non-2xx, the body additionally carries `upstream_status`.
```json theme={null}
{
"error": "wait duration must be positive",
"request_id": "9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"upstream_status": 400
}
```
## OpenAPI
````yaml POST /computers/{id}/wait
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: 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
paths:
/computers/{id}/wait:
post:
tags:
- Computer Actions
summary: Wait
description: >-
Pauses on the computer for the given duration, from just above 0 up to
60 seconds. The request blocks until the wait completes. A Windows
computer has no wait endpoint and answers `404`.
operationId: wait
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WaitRequest'
example:
seconds: 2
responses:
'200':
description: Wait completed
content:
application/json:
schema:
$ref: '#/components/schemas/ActionResponse'
example:
success: true
action: wait
details:
seconds: 2
error: null
error_type: null
'400':
description: >-
`seconds` is missing, `0`, negative, or over 60, the computer has no
VM attached, or a body field has the wrong JSON type.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/UpstreamError'
examples:
not-positive:
summary: Missing, zero, or negative
value:
error: wait duration must be positive
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 400
too-long:
summary: Over 60 seconds
value:
error: wait duration 1m5s exceeds maximum of 1m0s
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 400
no-instance:
summary: The computer has no VM attached. Start it first.
value:
error: Desktop instance not available
'401':
$ref: '#/components/responses/UnauthorizedWithAccess'
'402':
$ref: '#/components/responses/TrialInactive'
'404':
description: >-
No computer with this id, or the computer runs Windows, whose agent
has no wait endpoint (every wait answers `404` there).
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/UpstreamError'
examples:
no-computer:
summary: Unknown computer
value:
error: Desktop not found
windows:
summary: A Windows computer
value:
error: |
404 page not found
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 404
'500':
description: >-
The request body is not valid JSON, or the request failed for a
reason the API could not classify.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/UpstreamError'
- $ref: '#/components/schemas/InternalError'
example:
error: …
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
'503':
description: >-
The computer could not be reached. Safe to retry. Also returned when
the computer never finished provisioning, or when it did not answer
within 90 seconds (`code: "ECONNABORTED"`).
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/UnreachableError'
- $ref: '#/components/schemas/InternalError'
examples:
unreachable:
summary: Unreachable
value:
error: Could not reach the desktop. Try again in a moment.
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
code: ECONNREFUSED
aborted:
summary: The computer did not answer within 90 seconds
value:
error: Could not reach the desktop. Try again in a moment.
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
code: ECONNABORTED
not-ready:
summary: The computer never finished provisioning
value:
error: Computer not ready
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
components:
schemas:
WaitRequest:
type: object
required:
- seconds
properties:
seconds:
type: number
exclusiveMinimum: 0
maximum: 60
description: >-
How long to pause, in seconds. Must be greater than `0` and no more
than `60`; fractions are allowed. Missing, `0`, negative, or over 60
returns `400`.
duration:
type: number
exclusiveMinimum: 0
maximum: 60
deprecated: true
description: Deprecated alias for `seconds`. Read only when `seconds` is absent.
ActionResponse:
type: object
properties:
success:
type: boolean
description: Always `true` on a `200`. A failed action is an error status.
example: true
action:
type: string
description: >-
The action performed: `click`, `mouse_move`, `drag`, `type`,
`key_press`, `scroll`, or `wait`.
details:
type: object
additionalProperties: true
description: Echo of what was performed. Its fields depend on the action.
error:
type: 'null'
description: Always `null` on a `200`.
error_type:
type: 'null'
description: Always `null` on a `200`.
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.
UpstreamError:
type: object
description: >-
A failure the computer itself returned, relayed with the computer's own
status.
required:
- error
- request_id
- upstream_status
properties:
error:
type: string
description: The message the computer returned.
request_id:
type: string
description: >-
Correlation id for this failure. The server logged the failure under
it, so quote it in a support report.
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status:
type: integer
description: >-
The status the computer returned. Mirrors the status of this
response.
example: 409
InternalError:
type: object
description: >-
An unexpected failure. Retrying is reasonable; if it persists, quote
`request_id`.
required:
- error
properties:
error:
type: string
request_id:
type: string
description: >-
Present on failures raised by a route that talks to a computer.
Absent on the others.
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
UnreachableError:
type: object
description: >-
The computer could not be reached. The diagnostic fields, present on the
command endpoints, say how far the request got.
required:
- error
- request_id
- code
properties:
error:
type: string
example: Could not reach the desktop. Try again in a moment.
request_id:
type: string
example: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
code:
type: string
description: >-
The socket-level error code, or `network_error` when none was
reported.
example: ECONNREFUSED
vm_status:
type:
- string
- 'null'
description: The computer's recorded status when the request failed.
desired_status:
type:
- string
- 'null'
description: >-
The status the computer was being driven towards, when one was
recorded.
host_reachable:
type:
- boolean
- 'null'
description: Whether the host running the computer answered.
desktop_api_reachable:
type:
- boolean
- 'null'
description: Whether the computer's own API answered.
hint:
type: string
description: What to do next, given the two reachability results.
responses:
UnauthorizedWithAccess:
description: >-
No usable credential, or an access check failed. This endpoint runs its
workspace access checks during authentication, so it answers a missing
membership, view-only access, or a key scoped to another workspace with
`401`, not `403`. A server-side fault while verifying the credential
also returns `401`, with a `Service temporarily unavailable` message.
Retry that one; the key is fine.
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
no-access:
summary: Not the owner or a member of the workspace
value:
error: You do not have access to this workspace.
view-only:
summary: View-only member, and the request changes something
value:
error: >-
This workspace is view-only. Ask the owner for write access
(workspace_read_only).
scope-mismatch:
summary: The API key is scoped to another workspace
value:
error: >-
This API key cannot access this workspace
(workspace_scope_mismatch).
service-unavailable:
summary: Server-side fault while verifying the credential. Retry.
value:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
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.
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.