# Request options

> Shape one task with options on the request. Budgets, reasoning effort, background runs, earlier history, per-person memory and template values, all set per request.

Canonical URL: https://harnessrouter.ai/docs/request-options
Section: API reference

## Options

- **max_cost_usd:** The most this task may cost, in US dollars as we bill it.
- **timeout_seconds:** How long this turn may run.
- **max_step:** How many steps the agent may take in this turn.
- **reasoning:** `{"effort": ...}`, one of `none`, `minimal`, `low`, `medium`, `high` or `xhigh`; anything else is 400. A model without the level asked for gets the nearest one it supports.
- **background:** `true` returns at once and runs the task on its own; read the result later.
- **metadata:** Your own keys and values, returned with the response.
- **user:** Your id for the person the task is for, which keeps their Harness Memory apart.
- **prompt:** `{"variables": {...}}`, the values for a harness whose instructions are a template.

> **Budgets you leave out.** A budget left out of the request falls back to the harness's own, then to the defaults `GET /v1/bases` returns.

## Example

A capped task that runs in the background:

```
POST /{harness_id}/v1/responses
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "input": "Summarize this quarter's support tickets.",
  "max_cost_usd": 2,
  "timeout_seconds": 900,
  "reasoning": { "effort": "high" },
  "background": true,
  "metadata": { "ticket_batch": "2026-q4" }
}
```

- [Read a response](https://harnessrouter.ai/docs/read-a-response): Read a background task's result when it is done.

## Starting with earlier history

A request that starts a task may carry earlier user and assistant messages before the last user message. They become the agent's history, marked as imported, so a conversation that began somewhere else continues here. Imported turns are not billed.

Up to 20 earlier messages and 24,000 characters. Over either, nothing is imported and the whole input is read as one turn. `content` may be a string or a list of text parts.

Start from a conversation you already have:

```
{
  "input": [
    { "role": "user", "content": "Our refund window is 30 days." },
    { "role": "assistant", "content": "Understood." },
    { "role": "user", "content": "Draft the reply to this customer." }
  ]
}
```

## Open standard

These per-request fields ride on the same create-response body the Tasks chapter defines, so a budget or a reasoning level travels with the one task it is meant for instead of changing the harness. See [the task request in UHP's Tasks chapter](https://unifiedharnessprotocol.org/spec/tasks).
