---
title: "Run an inline prompt (async, no pre-created job)"
method: POST
path: "/runs"
---

# Run an inline prompt (async, no pre-created job)

`POST /runs`

## Request

- Base URL: `https://worker.openhelm.ai/v1`
- URL: `https://worker.openhelm.ai/v1/runs`
- Auth: HTTP bearer

One-call run: pass a `prompt` (with optional {{placeholders}} filled by `inputs`) and an optional `output_schema`. Returns 202 immediately; poll GET /runs/{id} or supply callback_url. `project_id` is optional — omit it and the run executes in the org's auto-created "API Runs" project.

## Request body

- object
  - `prompt` string, required
  - `inputs` object
  - `output_schema` object: Declares the result shape.
  - `model` 'haiku' | 'sonnet' | 'opus'
  - `project_id` string: Optional; defaults to the org's "API Runs" project.
  - `name` string: Optional label for the run.
  - `callback_url` string, uri: HMAC-signed completion webhook target.
  - `idempotency_key` string: Replays return the original run.

## Response `202`

Accepted

- object
  - `task_id` string
  - `status` 'queued'
  - `poll_url` string
  - `billing` BillingHint: An up-front cost ESTIMATE returned with a started run. The billed figure is always usage.cost_usd on the completed TaskEnvelope; this is a planning hint only and varies with task complexity and tools used.
    - `model` 'haiku' | 'sonnet' | 'opus'
    - `credit_usd_rate` number: USD value of one OpenHelm credit (1 credit = $0.05).
    - `estimated_cost_usd` object
      - `low` number
      - `high` number
    - `estimated_credits` object
      - `low` integer
      - `high` integer
    - `monthly_cap_usd` number, nullable: This API key's monthly spend cap, if set.
    - `note` string

## Other responses

- `402`: Subscription/trial/quota gate
- `429`: Too many concurrent runs

---

[API](https://skmtc.dev/openhelm/apis/openhelm-public-api.md) · [All operations](https://skmtc.dev/openhelm/apis/openhelm-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openhelm/apis/openhelm-public-api/revisions/2af88dc2f6a7?raw)