Skip to main content
POST
Create batch
Creates an async batch job.

Request shape

Choose one caller-facing endpoint for the batch:
  • /v1/chat/completions
  • /v1/responses
  • /v1/messages
  • /v1/embeddings
The selected endpoint defines the request-body shape for every row. Rows may omit url to inherit the batch endpoint. If a row supplies url, it must resolve to the same endpoint; mixed endpoint shapes are rejected. Declare model once at the top level to let rows inherit it. A row may repeat the same model, but a conflicting row model is rejected before provider submission. Phaseo also rejects streaming requests because batch results are delivered asynchronously. Use GET /batches/capabilities to inspect the endpoints supported by each enabled provider. Unsupported endpoint and provider combinations fail validation rather than being silently converted to another request shape. Phaseo also accepts these extra fields:
  • session_id to group the batch with related requests in logs and activity views
  • webhook to configure async notifications when the batch transitions state.
  • metadata to persist caller-defined tags alongside the batch.
Webhook events may use generic job.* names or matching batch.* names. Include job.progress or batch.progress to receive progress notifications when the provider reports request counts. If omitted, terminal job.completed, job.failed, job.cancelled, and job.expired events are used. If supplied, at least one event must be valid for batch jobs; cross-kind-only or malformed event lists are rejected. Webhook callback URLs must use HTTPS. Literal private, loopback, link-local, and wildcard hosts are rejected; http://localhost, http://127.0.0.1, and http://[::1] are allowed only for local development callbacks. Use GET /batches/models to discover batch-capable models and supported batch parameters, GET /batches to list owned batch jobs, GET /batches/{batch_id} to poll status, and POST /batches/{batch_id}/cancel to stop a pending or processing batch. Persist and poll the gateway-owned response id. When Phaseo also returns native_batch_id, that value is the provider-native id used for upstream correlation; do not use it in Phaseo polling, websocket, or cancellation URLs unless it is also the gateway id. Batch creation reserves gateway credits before submitting upstream when the input can be priced. If the gateway cannot read the input file or resolve pricing, creation fails before provider submission instead of starting unreserved work. If a provider submission times out or returns an ambiguous server error, Phaseo retains the reservation and marks the submission for reconciliation. It does not retry blindly or release credit while the provider may still be processing the accepted job. Definitive provider rejections release the reservation idempotently. Batch responses can also include:
  • request_id
  • native_batch_id when the provider id differs from the gateway id
  • provider
  • echoed session_id
  • sanitized webhook configuration and delivery state
  • lifecycle_status, polling_url, and cancel_url
  • billing reservation and settlement state, including held estimates before final settlement
  • terminal pricing_lines
Related endpoints:

Authorizations

Authorization
string
header
required

Bearer token authentication

Body

application/json
model
string

Model id used to infer the upstream batch provider. Request rows may also include body.model; the top-level model is preferred.

prompts
string[]

Simple prompt shorthand. Phaseo compiles each prompt into a provider-native batch row for the selected model.

items
object[]

Structured prompt shorthand. Items may include id, custom_id, prompt, messages, input, system, max_tokens, temperature, or an advanced body.

system
string

Optional system instruction applied to prompt shorthand rows.

max_tokens
integer

Optional max token limit applied to prompt shorthand rows.

temperature
number

Optional sampling temperature applied to prompt shorthand rows.

input_file_id
string

Existing provider file ID for file-upload batch creation.

requests
object[]

Advanced batch request rows. Provide exactly one of prompts, items, requests, or input_file_id.

endpoint
enum<string>

Caller-facing request shape. Every request in a batch uses this endpoint. Phaseo chooses a provider-native default from the model when omitted.

Available options:
/v1/chat/completions,
/v1/responses,
/v1/messages,
/v1/embeddings,
/v1/generateContent
completion_window
string
metadata
object
session_id
string

Unique identifier for grouping related requests (for example, a conversation or agent workflow) for observability.

Maximum string length: 256
webhook
object
webhook_endpoint_id
string

Convenience alias for webhook.endpoint_id.

debug
object

Gateway debug controls. These flags are never forwarded upstream.

provider
object

Advanced routing constraint. Most requests should rely on model-based provider inference.

Response

Batch status response

id
string
native_batch_id
string | null

Provider-native batch id when it differs from the gateway-owned id.

object
string
endpoint
string
errors
object
input_file_id
string
completion_window
string
status
string
lifecycle_status
enum<string>

Normalized async lifecycle status for polling, websocket, and webhook consumers.

Available options:
pending,
running,
completed,
failed,
cancelled,
expired
progress
integer

Coarse batch completion percentage derived from provider request counts when available. Completed batches report 100.

Required range: 0 <= x <= 100
polling_url
string<uri>
websocket_url
string<uri>

WebSocket URL for subscribing to normalized async job lifecycle updates.

cancel_url
string<uri> | null

Reserved for compatibility; currently always null.

output_file_id
string
error_file_id
string
created_at
integer
in_progress_at
integer
expires_at
integer
finalizing_at
integer
completed_at
integer
failed_at
integer
expired_at
integer
cancelling_at
integer
cancelled_at
integer
request_counts
object
metadata
object
request_id
string
provider
string
session_id
string
webhook
object

Sanitized async webhook configuration plus delivery state. Secrets are never returned; has_secret indicates whether signed deliveries are enabled. Signed deliveries include x-phaseo-signature, x-phaseo-timestamp, x-phaseo-event-id, x-phaseo-event-type, x-phaseo-delivery-key, x-phaseo-attempt, and x-phaseo-max-attempts headers.

next_webhook_retry_at
string | null
last_webhook_progress
number | null
last_webhook_progress_at
string | null
last_webhook_dispatched_at
string | null
finalized_at
string | null
pricing_lines
object[]
usage
object

Normalised aggregate usage and cost after finalisation.

billing
object
Last modified on August 4, 2026