# Create a Run

Execute a balance-funded tool request with a fixed contract, spending cap and idempotency key.

## Endpoint

Use funding.mode = balance on this endpoint. Wallet per_run funding uses the separate wallet-payment protocol, even though it shares the RunRequest schema.

Replace all example placeholders and supply an input matching the inspected schema. maxChargeMicros is an exact integer string; for balance funding, 1000000 micro-units equals 1 USD. Use the inspected price and unit. For successful_url pricing, cover every submitted URL in maxChargeMicros. The platform settles only successful URLs and releases the unused hold. For credit pricing, cover the maximum usage described in the quote. For max_call pricing, reserve the quoted maximum and read the actual charge from the Run. For executed_step pricing, cover max_steps and the finalization allowance in the quote. For browser_minute pricing, cover the requested lease minutes.

HTTP 422 json_too_large means the complete normalized request exceeded 1 MiB, including escaped strings, numbers in decimal form and defaults. Reduce the input before submitting again. The rejected request creates no Run or balance hold.

Within the same account workspace, the same idempotency key and effective request recover the original Run, even across different API keys. A changed request with the same idempotency key conflicts. Persist the full request before submission.

HTTP 202 means billing is still HELD or REVIEW; execution may already have ended. HTTP 200 does not prove successful execution. Keep runId and follow pollAfterMs. Execution, billing and result availability must be checked separately.

```
POST /v1/runs
```

## Request body

```
{
  "toolId": "<toolId from inspect>",
  "toolRevision": "<toolRevision from inspect>",
  "priceRevision": "<priceRevision from inspect>",
  "input": {
    "<required field>": "<value matching inputSchema>"
  },
  "idempotencyKey": "<unique key saved for this task>",
  "maxChargeMicros": "<integer spending cap in USD micro-units>",
  "funding": {
    "mode": "balance"
  }
}
```

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| toolId | string | Required | — |
| toolRevision | string | Required | — |
| priceRevision | string | Required | — |
| input | JSON value | Required | — |
| idempotencyKey | string | Required | Min length: 1; Max length: 128 |
| maxChargeMicros | string | Required | Pattern: ^[0-9]+$ |
| funding | object | Required | — |
| cacheControl | object | Optional / conditional | — |

## Request example

Set PURRKEY_API_KEY in your trusted server or terminal environment. Replace any angle-bracket placeholders with values from your own inspection or Run.

```
curl --fail-with-body --request POST 'https://api.purrkey.app/v1/runs' \
  -H "Authorization: Bearer $PURRKEY_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json
```

## Successful response

Success HTTP status: 200, 202. Top-level response fields are listed below. Conditional and nested requirements are defined in the downloadable OpenAPI contract.

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| runId | string | Required | — |
| toolId | string | Required | — |
| toolRevision | string | Required | — |
| toolName | string | Optional / conditional | — |
| status | string | Required | QUEUED \| SUBMITTING \| RUNNING \| WAITING_PROVIDER \| SUCCEEDED \| FAILED \| CANCELED \| TIMED_OUT \| UNKNOWN |
| billing | object | Required | — |
| createdAt | string | Required | date-time |
| updatedAt | string | Required | date-time |
| cancelRequestedAt | string | Optional / conditional | date-time |
| payment | object | Optional / conditional | — |
| input | JSON value | Optional / conditional | — |
| result | object | Required | — |
| error | object | Optional / conditional | — |
| pollAfterMs | integer | Optional / conditional | int32; Minimum: 0 |

## Errors and related reading

- [Error handling](/docs/guides/errors): Read requestId, business codes and safe retry behavior.
- [Download OpenAPI](/docs/openapi.yaml): The complete HTTP contract, version 0.4.3.