> ## 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. # Start a run > Run a workflow now. The run goes on in the background; a retry with the same Idempotency-Key never starts a second one. Starts a run of a workflow now, whether it is on or off, and answers `202` at once. The run goes on in the background: read it with [Get a run](https://docs.orgo.ai/api-reference/workflows/get-run.md), or follow it with [Follow a workflow](https://docs.orgo.ai/api-reference/workflows/events.md). A run uses the steps as they are when it starts; a later edit never changes a run already going. A run whose steps use the computer’s agents or screen wakes the computer as it starts, if it is asleep. ## Path parameters **id** `string` *required* The workflow’s id, like `morning-report`. ## Headers **Idempotency-Key** `string` 8 to 255 printable characters. A retry with the same key and inputs answers with the run the first request started, with `idempotent-replayed: true`, instead of starting another. The same key with other inputs answers `409` with `code: "idempotency_key_reused"`. **X-Agent** `string` Who started it, at most 30 characters, like `Claude Code`. The run’s `by` and the canvas say it. ## Request body **inputs** `object` What the run starts with, name to string value. They fill its settings and `{fill-ins}` for this run only. Optional. ## Response `202`, with the run. **run** `object` The run as it is now, in the shape [Get a run](https://docs.orgo.ai/api-reference/workflows/get-run.md) describes. `state` is `running`. ## Example ```bash cURL theme={null} curl -X POST https://www.orgo.ai/api/workflows/morning-report/runs \ -H "Authorization: Bearer $ORGO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"inputs":{}}' ``` ```python Python theme={null} import os, time, uuid, requests url = "https://www.orgo.ai/api/workflows/morning-report/runs" headers = {"Authorization": f"Bearer {os.environ['ORGO_API_KEY']}"} run = requests.post(url, headers={**headers, "Idempotency-Key": str(uuid.uuid4())}, json={"inputs": {}}).json()["run"] while run["state"] == "running": time.sleep(3) run = requests.get(f"{url}/{run['run_id']}", headers=headers).json()["run"] print(run["state"], run.get("output")) ``` ```javascript JavaScript theme={null} const r = await fetch("https://www.orgo.ai/api/workflows/morning-report/runs", { method: "POST", headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ inputs: {} }), }); const { run } = await r.json(); ``` ### Response ```json theme={null} { "run": { "run_id": "0d9c6c1e-5b8e-4a59-9d3b-7a1f2c3d4e5f", "state": "running", "at": 1793887204000, "by": "Claude Code", "inputs": {}, "steps": [], "output": null, "finished_at": null } } ``` ## Errors | Status | Code | When | | - | - | - | | `400` | `invalid_body` | `inputs` that are not names to strings, or an `Idempotency-Key` that is not 8 to 255 printable characters. | | `401` | | No key, or a key Orgo doesn’t know. | | `403` | `key_permission` | A restricted key without Workflows write, or without Control write and AI write for a workflow whose steps act on its computer. | | `404` | `not_found` | No workflow by that id. | | `404` | (no body) | Workflows aren’t open to your account. | | `409` | `not_started` | It didn’t start: too many of its runs are open. Carries `Retry-After: 60`. | | `409` | `computer_moved` | Its computer isn’t yours any more. Pick another with [Update a workflow](https://docs.orgo.ai/api-reference/workflows/update.md). | | `409` | `idempotency_key_reused` | That key was used with other inputs. | | `409` | `idempotency_key_spent` | That key started a run over a day ago. Send a new one to start another. | | `409` | `idempotency_busy` | A request with that key is still going. Retry after `retry_after` seconds. | | `413` | `body_too_large` | The body is over 64 KB. | | `422` | `not_ready` | It can’t run yet. `to_fix` says what to do, and `needs` names apps to connect on its computer. | | `422` | `computer_required` | It has no computer. Pick one with [Update a workflow](https://docs.orgo.ai/api-reference/workflows/update.md). | | `429` | `rate_limited` | More than 30 runs a minute for this workflow, or 120 for the account. Carries `Retry-After`. | | `503` | `runs_unavailable` | Runs can’t happen here right now. Nothing ran. Retry after a minute. | | `503` | | Orgo couldn’t verify the key because of a server-side fault. Retry. | ## OpenAPI ````yaml POST /workflows/{id}/runs 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: contact@orgo.ai url: https://orgo.ai servers: - url: https://www.orgo.ai/api description: Production security: - bearerAuth: [] tags: - name: Support description: >- Orgo’s support agent, for programs: ask how to do something in Orgo and get an answer with full URLs and copyable commands. - 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. - name: Workflows description: >- Routines that run the same way every time: a start, then steps. Make them from plain words or lines, check them, run them and follow their runs (in preview). paths: /workflows/{id}/runs: post: tags: - Workflows summary: Run a workflow now description: >- Body: { inputs } (optional, name to value: what the run starts with). The run goes on in the background: read it with GET /api/workflows/{id}/runs/{runId}, or follow GET /api/workflows/{id}/events. It can’t run yet: 422 not_ready with to_fix. Send an Idempotency-Key (8 to 255 printable characters) so a retry answers with the run the first request started (as it was then) instead of starting another. A workflow whose steps act on its computer takes a key with Control write and AI write too. parameters: - name: id in: path required: true schema: type: string pattern: ^[a-z0-9-]{1,60}$ example: morning-report - name: Idempotency-Key in: header required: false schema: type: string minLength: 8 maxLength: 255 description: >- A retry with the same key and body answers as the first request did, for a day. - name: X-Agent in: header required: false schema: type: string maxLength: 30 description: Who you are, as the canvas names you (like Claude Code). requestBody: required: false content: application/json: schema: type: object properties: inputs: type: object additionalProperties: type: string example: inputs: customer: Acme responses: '202': description: '{ run }, started.' content: application/json: schema: type: object required: - run properties: run: $ref: '#/components/schemas/WorkflowRun' example: run: run_id: 0d9c6c1e-5b8e-4a59-9d3b-7a1f2c3d4e5f state: running at: 1793887204000 by: Claude Code inputs: {} steps: [] output: null finished_at: null '400': description: >- inputs that are not names to strings (invalid_body), or a bad Idempotency-Key. content: application/json: schema: $ref: '#/components/schemas/WorkflowError' '401': description: Unauthenticated (with WWW-Authenticate and docs). content: application/json: schema: $ref: '#/components/schemas/WorkflowError' '403': description: >- A key without Workflows access at this level (key_permission); a key that may not act on the workflow’s computer (key_permission: Control write and AI write, or computer_key_held). content: application/json: schema: $ref: '#/components/schemas/WorkflowError' '404': description: >- No workflow (or run) by that id (not_found); a bare 404 with no body where Workflows are not open to the account. content: application/json: schema: $ref: '#/components/schemas/WorkflowError' '409': description: >- It didn’t start (not_started: off, or too many of its runs waiting), or an Idempotency-Key already used with other inputs (idempotency_key_reused) or still going (idempotency_busy). content: application/json: schema: $ref: '#/components/schemas/WorkflowError' '413': description: >- The body is too large (body_too_large): at most 64 KB, 128 KB for a PUT, 32 KB for an answer. content: application/json: schema: $ref: '#/components/schemas/WorkflowError' '422': description: >- It can’t run yet (not_ready, with to_fix; needs: apps to connect on its computer), or it has no computer (computer_required). content: application/json: schema: $ref: '#/components/schemas/WorkflowError' '429': $ref: '#/components/responses/RateLimited' '503': description: >- Runs can’t happen here right now (runs_unavailable), with Retry-After. Also when Orgo could not verify the credential because of a server-side fault (with Retry-After: 5). content: application/json: schema: $ref: '#/components/schemas/WorkflowError' components: schemas: WorkflowRun: type: object required: - run_id - state properties: run_id: type: string state: type: string enum: - running - waiting - done - stopped - needs_review at: type: integer description: When it started, in milliseconds since 1970. by: type: string description: Who started it. inputs: type: object steps: type: array items: type: object properties: id: type: string title: type: string kind: type: string how: type: string ms: type: integer output: {} output: description: What the last step to run handed on. waiting: type: object description: >- The step it waits at: id, title, asks (a person’s), agent and until (another agent’s). stop: type: object description: Why it stopped, and the one thing that fixes it. finished_at: type: - string - 'null' format: date-time WorkflowError: type: object required: - error - code properties: error: type: string code: type: string say: type: string description: The same, short, for a person. next: type: string description: The call that fixes it. to_fix: type: array items: type: string problems: type: array items: type: object version: type: - integer - 'null' description: 'version_conflict: the newest version.' lines: type: - string - 'null' description: 'version_conflict: the newest lines, to merge into.' RateLimited: type: object required: - error - code - limit - retry_after properties: error: type: string description: Which limit, in plain words, and when to try again. code: type: string const: rate_limited limit: type: string enum: - computer_create_per_minute - computer_create_per_hour - computer_create_per_day - computer_lifecycle_per_minute - computer_lifecycle_per_computer_per_minute - computer_control_per_minute - computer_control_per_computer_per_minute - chat_runs_per_minute - chat_runs_concurrent - workspace_create_per_hour - api_other_per_minute retry_after: type: integer minimum: 1 description: Seconds to wait. example: error: >- Too many API requests this minute (120 a minute on your plan). Try again in 12 seconds. code: rate_limited limit: api_other_per_minute retry_after: 12 responses: RateLimited: description: >- Over one of the account's plan rate limits (`rate_limited`): `limit` names it, and `retry_after` and `Retry-After` say how many seconds to wait. Limits are per account, the workspace owner's when the request acts on a computer or a workspace, and set by its plan. See [Account limits and rate limits](/guides/account-limits#plan-rate-limits). headers: Retry-After: $ref: '#/components/headers/RetryAfter' RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/RateLimited' headers: RetryAfter: description: Seconds to wait before asking again. schema: type: integer minimum: 1 RateLimitLimit: description: The tightest limit this request counts against. schema: type: integer RateLimitRemaining: description: How many are left of it in this window. schema: type: integer RateLimitReset: description: Seconds until its window starts again. schema: type: integer 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.