Create a batch
Internal testing. The Batch API is available only to enabled workspaces. Requests from other workspaces return 403, and the API may change before general availability.
Create an async batch job and attach observability metadata such as session ids and webhooks.
Request shape
Choose one caller-facingendpoint for the batch:
/v1/chat/completions/v1/responses/v1/messages/v1/embeddings
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_idto group the batch with related requests in logs and activity viewswebhookto configure async notifications when the batch transitions state.metadatato persist caller-defined tags alongside the batch.
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_idnative_batch_idwhen the provider id differs from the gateway idprovider- echoed
session_id - sanitized
webhookconfiguration and delivery state lifecycle_status,polling_url, andcancel_urlbillingreservation and settlement state, including held estimates before final settlement- terminal
pricing_lines
Authorizations
Bearer token authentication
Body
Model id used to infer the upstream batch provider. Request rows may also include body.model; the top-level model is preferred.
Simple prompt shorthand. Phaseo compiles each prompt into a provider-native batch row for the selected model.
Structured prompt shorthand. Items may include id, custom_id, prompt, messages, input, system, max_tokens, temperature, or an advanced body.
Optional system instruction applied to prompt shorthand rows.
Optional max token limit applied to prompt shorthand rows.
Optional sampling temperature applied to prompt shorthand rows.
Existing provider file ID for file-upload batch creation.
Advanced batch request rows. Provide exactly one of prompts, items, requests, or input_file_id.
Caller-facing request shape. Every request in a batch uses this endpoint. Phaseo chooses a provider-native default from the model when omitted.
/v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings, /v1/generateContent Unique identifier for grouping related requests (for example, a conversation or agent workflow) for observability.
256Convenience alias for webhook.endpoint_id.
Gateway debug controls. These flags are never forwarded upstream.
Advanced routing constraint. Most requests should rely on model-based provider inference.
Response
Batch status response
Provider-native batch id when it differs from the gateway-owned id.
Normalized async lifecycle status for polling, websocket, and webhook consumers.
pending, running, completed, failed, cancelled, expired Coarse batch completion percentage derived from provider request counts when available. Completed batches report 100.
0 <= x <= 100WebSocket URL for subscribing to normalized async job lifecycle updates.
Reserved for compatibility; currently always null.
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.
Normalised aggregate usage and cost after finalisation.