Gateway

Create batch

Creates an async batch job and returns the upstream batch object. Batch creation supports OpenAI, Anthropic, Google Gemini, Mistral, xAI, Groq, and Together AI through the requested model. The gateway infers the upstream provider from the model and also accepts session_id and webhook for observability and async notifications. Use provider only as an advanced routing constraint.

post/batches

Request

  • Base URL: https://api.phaseo.app/v1
  • URL: https://api.phaseo.app/v1/batches
  • Auth: HTTP bearer

Request body

provider_optionsobject

Extensions scoped by canonical provider ID. OpenAI accepts output_expires_after; Mistral accepts metadata. Only the selected provider's options are applied. Do not duplicate an option at the top level. Options cannot override priced rows, models or files.

modelstring

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

promptsstring[]

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

itemsobject[]

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

systemstring

Optional system instruction applied to prompt shorthand rows.

max_tokensinteger

Optional max token limit applied to prompt shorthand rows.

temperaturenumber

Optional sampling temperature applied to prompt shorthand rows.

input_file_idstring

Existing provider file ID for file-upload batch creation.

endpoint'/v1/chat/completions' | '/v1/responses' | '/v1/messages' | '/v1/embeddings' | '/v1/generateContent'

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

completion_windowstring
metadataobject
session_idstring

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

webhook_endpoint_idstring

Convenience alias for webhook.endpoint_id.

Response

Batch status response

idstring
native_batch_idstring nullable

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

objectstring
endpointstring
errorsobject
input_file_idstring
completion_windowstring
statusstring
lifecycle_status'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'expired'

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

progressinteger

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

polling_urlstring uri
websocket_urlstring uri

WebSocket URL for subscribing to normalized async job lifecycle updates.

cancel_urlstring uri nullable

Reserved for compatibility; currently always null.

results_urlstring uri nullable

Authenticated Phaseo JSONL download URL for terminal supported batches. Null while processing. A terminal batch may have no output. Use an API key from the owning workspace; provider retention limits apply.

output_file_idstring
error_file_idstring
created_atinteger
in_progress_atinteger
expires_atinteger
finalizing_atinteger
completed_atinteger
failed_atinteger
expired_atinteger
cancelling_atinteger
cancelled_atinteger
metadataobject
request_idstring
providerstring
session_idstring
next_webhook_retry_atstring nullable
last_webhook_progressnumber nullable
last_webhook_progress_atstring nullable
last_webhook_dispatched_atstring nullable
finalized_atstring nullable
pricing_linesobject[]

Example response

{
  "webhook": {
    "delivery": {
      "delivered_event_types": [
        "video.completed"
      ]
    },
    "attempts": [
      {
        "delivery_key": "video.completed",
        "event_type": "video.completed"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.