> ## 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.
# Take screenshot
> Capture the display as a stored URL, inline base64, or image bytes.
Captures the computer's display. By default it returns a stored image URL. Use `response_format=binary` for image bytes in the same response, or `response_format=base64` for inline JSON. Inline responses skip storage and a second download.
## Path parameters
Computer ID (UUID). An `instance_id` is not accepted here and fails with `500`.
## Query parameters
Which [screen](/api-reference/screens/list) to capture. Optional. Omit it to
capture the screen the computer booted with. An unknown id returns `404`
rather than falling back to the default screen. A Windows computer ignores
this parameter.
`url`, `base64`, or `binary`. Binary returns the image with its actual Content-Type.
Base64 returns `{success, image, mime_type, width, height}`, where `image` is raw base64.
`png`, `jpeg`, or `webp`. Omit to preserve the captured format.
An integer from 1 through 100. Applies when the image is re-encoded as JPEG
or WebP, which happens when you request a `format` or a `scale` below 1.
Greater than 0 and at most 1. For example, 0.5 halves both dimensions.
For a smaller response, request `?response_format=binary&format=webp&quality=75&scale=0.5`.
## URL response
Always `true` on a `200`. A failed capture is an error status, not `success: false`.
Path to the stored image, **relative to `https://www.orgo.ai`**. For example:
`/api/storage/4d96f9a0-1c2b-4f3e-9a7d-8b5c6e0f1a2d/2026-04-20T12-00-00-000Z_9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d.png`.
It is not an absolute URL, so join it to the origin before fetching. The path
does not expire, but it is not public: fetch it with the same
`Authorization` header, as an account that can view the computer's
workspace. A request without credentials returns `401`, and one without
access returns `404`. A workspace-scoped key cannot fetch it at all (`403`),
so use `response_format=base64` or `binary` with a scoped key.
Information about the stored image.
Screenshot record ID (UUID). It also appears in `storage_path`, after the timestamp.
ISO 8601 creation timestamp.
Size of the stored image in bytes.
Object key in storage: `/_.`,
where the extension is `png`, `jpg`, or `webp`.
`image` is this key served through `/api/storage/`.
Stored filenames and Content-Type match the encoded image: `.png`, `.jpg`, or `.webp`. Inline responses use `Cache-Control: private, no-store`.
## Example
```bash cURL theme={null}
curl https://www.orgo.ai/api/computers/$COMPUTER_ID/screenshot \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import requests
response = requests.get(
f"https://www.orgo.ai/api/computers/{computer_id}/screenshot",
headers={"Authorization": f"Bearer {api_key}"}
)
data = response.json()
# `image` is relative. Join it to the origin and send the same key.
img = requests.get(
"https://www.orgo.ai" + data["image"],
headers={"Authorization": f"Bearer {api_key}"}
)
with open("screenshot.png", "wb") as f:
f.write(img.content)
```
```javascript JavaScript theme={null}
import fs from 'node:fs';
const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}/screenshot`, {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const { image } = await response.json();
// `image` is relative. Join it to the origin and send the same key.
const img = await fetch(`https://www.orgo.ai${image}`, {
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const buffer = Buffer.from(await img.arrayBuffer());
fs.writeFileSync('screenshot.png', buffer);
```
### Response
```json theme={null}
{
"success": true,
"image": "/api/storage/4d96f9a0-1c2b-4f3e-9a7d-8b5c6e0f1a2d/2026-04-20T12-00-00-000Z_9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d.png",
"metadata": {
"id": "9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"timestamp": "2026-04-20T12:00:00.000Z",
"size": 187342,
"storage_path": "4d96f9a0-1c2b-4f3e-9a7d-8b5c6e0f1a2d/2026-04-20T12-00-00-000Z_9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d.png"
}
}
```
## Errors
| Status | Meaning |
| - | - |
| `400` | Invalid response format, image format, quality, or scale. Also returned when the computer has no VM attached: `{"error": "Desktop instance not available"}`. Start it first. |
| `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, 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"}`. Also returned when `?screen=` names a screen this computer does not have. |
| `500` | The capture or the upload failed. |
| `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": "Could not reach the desktop. Try again in a moment.",
"request_id": "9f2b7c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
"code": "ECONNREFUSED"
}
```
## OpenAPI
````yaml GET /computers/{id}/screenshot
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}/screenshot:
get:
tags:
- Computer Actions
summary: Take screenshot
description: >-
Capture the display. Default returns a stored image URL; binary and
base64 return the image without a storage upload.
operationId: getScreenshot
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
- name: screen
in: query
required: false
description: >-
Which screen to act on. Omit for the boot screen. An unknown id
returns 404 rather than falling back.
schema:
type: string
- name: response_format
in: query
description: How to return the image.
schema:
type: string
enum:
- url
- base64
- binary
default: url
- name: format
in: query
description: Optional output encoding. Omit to preserve the guest encoding.
schema:
type: string
enum:
- png
- jpeg
- webp
- name: quality
in: query
description: JPEG/WebP encoding quality. Use with an explicit format.
schema:
type: integer
minimum: 1
maximum: 100
default: 80
- name: scale
in: query
description: >-
Image dimensions as a fraction of the source. Coordinates in
click/type APIs remain unscaled.
schema:
type: number
exclusiveMinimum: 0
maximum: 1
default: 1
responses:
'200':
description: Screenshot captured
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
image:
type: string
description: Stored URL for url mode; raw base64 for base64 mode.
mime_type:
type: string
width:
type: integer
height:
type: integer
metadata:
type: object
image/png:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
image/webp:
schema:
type: string
format: binary
'400':
description: >-
Invalid `response_format`, `format`, `quality`, or `scale`, or the
computer has no VM attached.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Desktop instance not available
'401':
$ref: '#/components/responses/UnauthorizedWithReadAccess'
'402':
$ref: '#/components/responses/TrialInactive'
'404':
description: >-
No computer with this id, or `?screen=` names a screen this computer
does not have.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/UpstreamError'
examples:
no-computer:
summary: Unknown computer
value:
error: Desktop not found
no-screen:
summary: Unknown screen
value:
error: no screen "2"
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
upstream_status: 404
'500':
description: The capture or the upload failed.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/UpstreamError'
- $ref: '#/components/schemas/InternalError'
example:
error: Failed to capture screenshot
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
'503':
description: >-
The computer could not be reached. It may be resuming, or its host
may be unhealthy. Retry in a moment. Also returned when the computer
never finished provisioning.
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
not-ready:
summary: The computer never finished provisioning
value:
error: Computer not ready
request_id: 7c1e0f4a-9b2d-4a51-8f0c-2d6b1e93a4c7
components:
schemas:
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:
UnauthorizedWithReadAccess:
description: >-
No usable credential, or an access check failed. This endpoint runs its
workspace access checks during authentication, so it answers a missing
membership 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.
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.