> ## 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.
# List clients
> Your clients, newest first, with the total and what they pay you each month.
Returns active clients unless you ask for closed ones. The `total` counts every match, not just this page, and `collecting` sums what paying clients send you each month.
Use your account-wide API key. A client’s own key gets `403` here. See [Invoicing](/guides/invoicing).
## Query parameters
Matches `name` or `external_id`.
`closed` lists closed clients. Anything else lists active ones.
Up to 200. Defaults to 50.
The `next` value from the previous page.
## Response
Clients, newest first. See [Get client](/api-reference/clients/get) for each field.
Pass as `before` for the next page, or `null` on the last one.
Clients matching the filters, across every page.
`clients` paying you, and `usd_per_month` they pay in all.
## Example
```bash cURL theme={null}
curl https://www.orgo.ai/api/v1/accounts \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import os
import requests
res = requests.get(
f"https://www.orgo.ai/api/v1/accounts",
headers={"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"},
)
print(res.json())
```
```javascript JavaScript theme={null}
const res = await fetch(`https://www.orgo.ai/api/v1/accounts`, {
headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` },
});
console.log(await res.json());
```
### Response
```json theme={null}
{
"accounts": [
{
"id": "8f14e45f-ceea-467a-9575-6f1c2b3d4e5f",
"external_id": "acme-dental",
"name": "Acme Dental",
"status": "active",
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": "2026-10-01T09:00:00Z",
"closed_at": null,
"limits": {
"max_computers": 3,
"monthly_ai_cap_usd": 40
},
"usage": {
"computers": 2,
"ai_spend_usd_this_month": 12.4
},
"billing": {
"status": "active",
"price_usd": 250,
"email": "billing@acme.com"
},
"transfer": null
}
],
"next": null,
"total": 1,
"collecting": {
"clients": 1,
"usd_per_month": 250
}
}
```
## Errors
| Status | Body | Meaning |
| - | - | - |
| `401` | `{ "error": "Invalid API key" }` | No key, or not one of yours. |
| `403` | `{ "error": "Use your account-wide API key to manage accounts. Workspace keys can’t." }` | A client’s own key, or any key scoped to one workspace. |
| `403` | `{ "error": "Invoicing is on every paid plan. Upgrade to use it." }` | You’re on the Free plan. `code` is `UPGRADE_REQUIRED`. |
## OpenAPI
````yaml GET /v1/accounts
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:
/v1/accounts:
get:
tags:
- Clients
summary: List clients
description: >-
Your clients, newest first, with the total and what they pay you each
month.
operationId: listClients
parameters:
- name: search
in: query
required: false
description: Matches `name` or `external_id`.
schema:
type: string
- name: status
in: query
required: false
description: '`closed` lists closed clients. Anything else lists active ones.'
schema:
type: string
- name: limit
in: query
required: false
description: Up to 200. Defaults to 50.
schema:
type: integer
- name: before
in: query
required: false
description: The `next` value from the previous page.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
example:
accounts:
- id: 8f14e45f-ceea-467a-9575-6f1c2b3d4e5f
external_id: acme-dental
name: Acme Dental
status: active
workspace_id: 550e8400-e29b-41d4-a716-446655440000
created_at: '2026-10-01T09:00:00Z'
closed_at: null
limits:
max_computers: 3
monthly_ai_cap_usd: 40
usage:
computers: 2
ai_spend_usd_this_month: 12.4
billing:
status: active
price_usd: 250
email: billing@acme.com
transfer: null
next: null
total: 1
collecting:
clients: 1
usd_per_month: 250
schema:
$ref: '#/components/schemas/ClientList'
'401':
description: No key, or not one of yours.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
e1:
summary: No key, or not one of yours
value:
error: Invalid API key
'403':
description: >-
A client’s own key, or any key scoped to one workspace. You’re on
the Free plan. `code` is `UPGRADE_REQUIRED`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
e1:
summary: A client’s own key, or any key scoped to one workspace
value:
error: >-
Use your account-wide API key to manage accounts.
Workspace keys can’t.
e2:
summary: You’re on the Free plan
value:
error: Invoicing is on every paid plan. Upgrade to use it.
components:
schemas:
ClientList:
type: object
properties:
accounts:
type: array
items:
$ref: '#/components/schemas/Client'
next:
type: string
nullable: true
total:
type: integer
collecting:
type: object
properties:
clients:
type: integer
usd_per_month:
type: number
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.
Client:
type: object
description: 'A client: a workspace you run for them, with a key scoped to it.'
properties:
id:
type: string
external_id:
type: string
name:
type: string
nullable: true
status:
type: string
enum:
- active
- closed
- transferred
workspace_id:
type: string
created_at:
type: string
format: date-time
closed_at:
type: string
format: date-time
nullable: true
limits:
type: object
properties:
max_computers:
type: integer
nullable: true
monthly_ai_cap_usd:
type: number
nullable: true
usage:
type: object
properties:
computers:
type: integer
ai_spend_usd_this_month:
type: number
billing:
type: object
nullable: true
properties:
status:
type: string
enum:
- sent
- active
- past_due
price_usd:
type: number
email:
type: string
transfer:
type: object
nullable: true
properties:
email:
type: string
sent_at:
type: string
format: date-time
computers:
type: array
description: On Get client only.
items:
type: object
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.