Skip to main content
POST
/
batches
Create batch
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input_file_id: '<string>',
    endpoint: '<string>',
    completion_window: '<string>',
    metadata: {},
    session_id: '<string>',
    webhook: {url: '<string>', secret: '<string>', events: ['<string>']},
    debug: {
      enabled: true,
      return_upstream_request: true,
      return_upstream_response: true,
      trace: true
    },
    provider: {
      order: ['<string>'],
      only: ['<string>'],
      ignore: ['<string>'],
      include_alpha: true
    }
  })
};

fetch('https://api.phaseo.app/v1/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "id": "<string>",
  "object": "<string>",
  "endpoint": "<string>",
  "errors": {},
  "input_file_id": "<string>",
  "completion_window": "<string>",
  "status": "<string>",
  "output_file_id": "<string>",
  "error_file_id": "<string>",
  "created_at": 123,
  "in_progress_at": 123,
  "expires_at": 123,
  "finalizing_at": 123,
  "completed_at": 123,
  "failed_at": 123,
  "expired_at": 123,
  "cancelling_at": 123,
  "cancelled_at": 123,
  "request_counts": {
    "total": 123,
    "completed": 123,
    "failed": 123
  },
  "metadata": {},
  "request_id": "<string>",
  "provider": "<string>",
  "session_id": "<string>",
  "webhook": {
    "url": "<string>",
    "secret": "<string>",
    "events": [
      "<string>"
    ]
  },
  "pricing_lines": [
    {}
  ],
  "billing": {
    "billed": true,
    "charged": true,
    "reason": "<string>",
    "cost_nanos": 123,
    "cost_usd": 123,
    "finalized_at": "<string>",
    "pricing_breakdown": {}
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.ai-stats.phaseo.app/llms.txt

Use this file to discover all available pages before exploring further.

Create a batch job for asynchronous processing. The gateway forwards the upstream batch request and also accepts AI Stats-specific observability fields:
  • session_id to group the batch with related requests in logs and investigate tooling.
  • webhook to configure async notifications when the batch transitions state.
  • metadata to persist caller-defined tags alongside the batch.
Use GET /batches/{batch_id} to poll status and POST /batches/{batch_id}/cancel to stop a pending or processing batch. Batch responses also include gateway observability fields when available:
  • request_id
  • provider
  • echoed session_id
  • echoed webhook
  • terminal billing summary data
  • terminal pricing_lines

Authorizations

Authorization
string
header
required

Bearer token authentication

Body

application/json
input_file_id
string
required
endpoint
string
required
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
debug
object

Gateway debug controls. These flags are never forwarded upstream.

provider
object

Provider routing preferences for gateway selection.

Response

Batch status response

id
string
object
string
endpoint
string
errors
object
input_file_id
string
completion_window
string
status
string
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
pricing_lines
object[]
billing
object
Last modified on May 6, 2026