---
title: "Run a job with parameters (async)"
method: POST
path: "/jobs/{id}/runs"
---

# Run a job with parameters (async)

`POST /jobs/{id}/runs`

## Request

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

Returns 202 immediately; poll GET /runs/{id} or supply callback_url.

## Request body

- object
  - `inputs` object
  - `output_schema` object: Overrides the job's output_schema for this 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)