Completion windows at a glance
A completion window sets how much wall-clock time per turn you’re willing to trade for a lower rate. Valar runs four. Choose one withmetadata.completion_window (or the X-Valar-Completion-Window header). Each is detailed in Completion windows below.
Each model’s rates per window are on the Pricing page.
The three modes
Realtime
A normal synchronous request that returns the result immediately. You send the call withoutbackground and read the output from the response. This is the lowest-latency path, finishing in seconds, and it runs on the Now completion window.
Realtime works across the Responses API (/v1/responses), Chat Completions (/v1/chat/completions). Use it for interactive chat, prototyping, and human-in-the-loop steps.
Tell Valar your client timeout
If your client gives up on a realtime call after a fixed time, tell Valar what that time is with theX-Valar-Client-Timeout header. It is read on every realtime endpoint: /v1/responses, /v1/chat/completions and /v1/messages.
It changes what happens when a request produces nothing. Without it, Valar works to its own limits, which are longer than most clients wait: your client can time out while the request is still running, and all you see is a connection that stopped. With it, the request ends at your number and tells you why.
The value is your timeout in seconds ("120"), or a duration ("2m", "90s"). It must be at least one second. Values longer than Valar’s own realtime limit are treated as that limit. Without the header Valar plans against its own limit, so set it to the timeout your SDK is actually configured with:
Either way the request is recorded as failed, and it ends when you said you would stop waiting rather than later. The header does not change your prices, your rate limits, or which models you can call, and it is not a guarantee that an answer arrives inside the time you give — a model that needs longer than your budget will simply be reported as a timeout sooner.
The header applies to realtime calls only. A request on one of the async windows is not waiting on a live connection, so it carries no client timeout.
Async
Setbackground=True on the Responses API, Chat Completions, or the Messages API. The create call returns a response id immediately, then you poll the retrieve endpoint or receive a webhook when the work finishes. On the Standard window a turn takes at most a minute and is usually much faster, so async clears high throughput at lower cost.
Async jobs usually run on the Standard window (standard), the lower-cost choice. Set it explicitly with metadata.completion_window: without a window, a background request still runs and is billed on Now (see Default behavior). Use async for agent loops, background jobs, and large fan-out. See Sending requests at scale.
background is a Valar extension there, so pass it through extra_body. The call returns 202 with a response object right away; poll the same retrieve endpoint with its id, and once the run succeeds it returns the finished chat completion.
background is a Valar extension there too, so pass it through extra_body with the Anthropic SDK. The call returns 202 with a response object right away; poll the same retrieve endpoint with its id, and once the run succeeds it returns the finished Anthropic message. See Anthropic SDK.
background waits for the result on the open connection, for up to five minutes. If the result isn’t ready by then, all three endpoints return 202 with the in-progress response object instead of an error, so you can keep polling its id rather than resending the request.
If you close the connection on a streamed request on an async window before it finishes, and nothing else can collect the answer (you sent no Idempotency-Key and named no webhook), Valar stops the request. It ends as cancelled and, like any cancelled request, is not billed. On the Responses API the stream has already handed you the response id in response.created, so the request keeps running to the end and you can retrieve it. With an Idempotency-Key or a webhook it also keeps running, and a retry with the same key or the webhook delivers the result.
background can’t be combined with stream: true on any of the three endpoints: that request is rejected with a 400.
Batch (Private Preview)
Batch lets you submit many requests at once as an uploaded JSONL file and retrieve a results file when the set completes - the lowest cost and highest throughput, with the longest turnaround (results land within the batch window, up to 12 hours). It follows the OpenAI Batch API, so existingclient.batches.create() code works unchanged. For the end-to-end workflow, see Sending requests at scale.
Compare the modes
Completion windows
A completion window tells Valar how much wall-clock time per turn your workload can tolerate, and you pay less the more time you give it. There are four, from fastest to cheapest:
Realtime uses the Now window; async work uses Priority for a firm ~10 s deadline, Standard for lower cost, or Flex for the cheapest background runs. Each model-and-window price pairing is on the Pricing page.
Set the window
Passmetadata.completion_window on the request:
X-Valar-Completion-Window header to the same value. This is useful when a client owns the request body on your behalf (for example, the Claude Agent SDK) and body metadata isn’t available. The body field takes precedence when both are set.
Accepted values are "asap" (Now), "priority", "standard", and "flex".
How each tier behaves
Now runs immediately on the fastest available hardware in a latency-optimized setup, at the higher on-demand rate. Use it for realtime, interactive requests where a person or another system is waiting on the result. Priority is a durable async window that targets a tight ~10-second turn-time ceiling - a firm, low-latency completion target for agent loops - priced below the Now rate. Like the other async windows, request it explicitly withbackground=True.
Standard runs on Valar’s maximum-efficiency serving stack with a turn-time ceiling of one minute - and in practice most turns complete much faster than that. Most of Valar’s published prices reference this window, and it’s the right choice for async agent loops and batch jobs. Request it explicitly with metadata.completion_window: "standard".
Flex is the lowest-cost tier, for background bulk work that can tolerate a little extra latency. It targets a turn-time ceiling of about five minutes and requires background=True - it isn’t available for realtime or synchronous calls. On the Responses API, a flex request without background=True, or with stream=True, is rejected with a 400; Chat Completions rejects synchronous and streaming flex requests the same way, so send flex work through the Responses API with background=True and poll for the result. The Messages API accepts flex without streaming: send background: true to get a 202 and poll for the result, or the call waits for up to five minutes and returns 202 with the in-progress response if the result isn’t ready by then (see Anthropic SDK). Streaming is never available on flex. Flex is always explicit: Valar never selects it for you, so request it with metadata.completion_window: "flex" when you want it.
Default behavior
Leavecompletion_window off (in both the body and the X-Valar-Completion-Window header) and the request runs on the Now window and is billed at the Now rate. This applies on the Responses, Chat Completions, and Messages APIs, and background=True alone doesn’t change it: a background request with no window still runs and is billed as Now. To pay the lower async rates, set Priority, Standard, or Flex explicitly.
Next steps
Quickstart
Send your first request with an OpenAI-compatible client.
Sending requests at scale
Fan out async and batch work across many requests.