> ## Documentation Index
> Fetch the complete documentation index at: https://phaseo.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Batches (Beta)

> Create an async batch job and attach observability metadata such as session ids and webhooks.

Creates an async batch job.

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.

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:

* [Batch models](./batches-models.mdx)
* [Batch list](./batches-list.mdx)
* [Batch status](./batches-status.mdx)
* [Cancel batch](./batches-cancel.mdx)


## OpenAPI

````yaml POST /batches
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    A gateway API for accessing various AI models with OpenAI-compatible
    endpoints.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.ai/v1
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /batches:
    post:
      tags:
        - Gateway
      summary: Create batch
      description: >-
        Creates an async batch job and returns the upstream batch object. The
        gateway also accepts `session_id` and `webhook` for observability and
        async notifications.
      operationId: createBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch status response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BatchRequest:
      type: object
      required:
        - input_file_id
        - endpoint
      properties:
        input_file_id:
          type: string
        endpoint:
          type: string
        completion_window:
          type: string
        metadata:
          type: object
          additionalProperties: true
        session_id:
          type: string
          maxLength: 256
          description: >-
            Unique identifier for grouping related requests (for example, a
            conversation or agent workflow) for observability.
        webhook:
          type: object
          properties:
            url:
              type: string
              format: uri
              description: >-
                HTTPS callback URL for gateway-managed webhooks. 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.
            secret:
              type: string
            events:
              type: array
              description: >-
                Optional event subscriptions. Use generic job.* events or
                matching batch.* events, for example batch.progress or
                batch.completed. When omitted, terminal job.* events are used.
                Include job.progress or batch.progress explicitly for
                request-count progress callbacks. When supplied, at least one
                event must be valid for batch jobs; cross-kind-only or malformed
                event lists are rejected.
              items:
                type: string
        debug:
          $ref: '#/components/schemas/DebugOptions'
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
    BatchResponse:
      type: object
      properties:
        id:
          type: string
        native_batch_id:
          type: string
          nullable: true
          description: Provider-native batch id when it differs from the gateway-owned id.
        object:
          type: string
        endpoint:
          type: string
        errors:
          type: object
        input_file_id:
          type: string
        completion_window:
          type: string
        status:
          type: string
        lifecycle_status:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
            - cancelled
            - expired
          description: >-
            Normalized async lifecycle status for polling, websocket, and
            webhook consumers.
        progress:
          type: integer
          minimum: 0
          maximum: 100
          description: >-
            Coarse batch completion percentage derived from provider request
            counts when available. Completed batches report 100.
        polling_url:
          type: string
          format: uri
        websocket_url:
          type: string
          format: uri
          description: >-
            WebSocket URL for subscribing to normalized async job lifecycle
            updates.
        cancel_url:
          type: string
          format: uri
          nullable: true
        output_file_id:
          type: string
        error_file_id:
          type: string
        created_at:
          type: integer
        in_progress_at:
          type: integer
        expires_at:
          type: integer
        finalizing_at:
          type: integer
        completed_at:
          type: integer
        failed_at:
          type: integer
        expired_at:
          type: integer
        cancelling_at:
          type: integer
        cancelled_at:
          type: integer
        request_counts:
          $ref: '#/components/schemas/BatchRequestCounts'
        metadata:
          type: object
        request_id:
          type: string
        provider:
          type: string
        session_id:
          type: string
        webhook:
          $ref: '#/components/schemas/AsyncWebhookPublicState'
        next_webhook_retry_at:
          type: string
          nullable: true
        last_webhook_progress:
          type: number
          nullable: true
        last_webhook_progress_at:
          type: string
          nullable: true
        last_webhook_dispatched_at:
          type: string
          nullable: true
        finalized_at:
          type: string
          nullable: true
        pricing_lines:
          type: array
          items:
            type: object
            additionalProperties: true
        billing:
          $ref: '#/components/schemas/BatchBillingSummary'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        ok:
          type: boolean
          example: false
        error:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          example: error_type
        message:
          type: string
          example: Human-readable error message
        description:
          type: string
          example: Additional error details.
        generation_id:
          type: string
          example: G-abc123
        status_code:
          type: integer
          example: 502
        error_type:
          type: string
          enum:
            - user
            - system
          example: system
        error_origin:
          type: string
          enum:
            - user
            - gateway
            - upstream
          example: upstream
        reason:
          type: string
          example: all_candidates_failed
        attempt_count:
          type: integer
          example: 2
        failed_providers:
          type: array
          items:
            type: string
          example:
            - google-ai-studio
            - openai
        failed_statuses:
          type: array
          items:
            type: integer
          example:
            - 403
            - 429
        upstream_error:
          $ref: '#/components/schemas/ErrorUpstreamError'
        failure_sample:
          type: array
          items:
            $ref: '#/components/schemas/ErrorFailureSampleItem'
        provider_failure_diagnostics:
          $ref: '#/components/schemas/ErrorProviderFailureDiagnostics'
        routing_diagnostics:
          $ref: '#/components/schemas/ErrorRoutingDiagnostics'
        provider_candidate_diagnostics:
          $ref: '#/components/schemas/ErrorProviderCandidateDiagnostics'
        provider_enablement:
          $ref: '#/components/schemas/ErrorProviderEnablementDiagnostics'
        missing_pricing_providers:
          type: array
          items:
            type: string
        provider_payment_required_provider:
          type: string
          example: openai
        provider_payment_required_support_notice:
          type: string
          example: >-
            Our upstream provider billing appears to be unavailable. If this
            persists, contact support.
        details:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    DebugOptions:
      type: object
      description: Gateway debug controls. These flags are never forwarded upstream.
      properties:
        enabled:
          type: boolean
        return_upstream_request:
          type: boolean
        return_upstream_response:
          type: boolean
        trace:
          type: boolean
        trace_level:
          type: string
          enum:
            - summary
            - full
    ProviderRoutingOptions:
      type: object
      description: Provider routing preferences for gateway selection.
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: Include alpha providers in routing (off by default).
        allow_fallbacks:
          type: boolean
          nullable: true
          description: Allow fallback to another eligible provider after failure.
        require_parameters:
          type: boolean
          nullable: true
          description: Require provider support for requested parameters before routing.
        required_execution_region:
          type: string
          nullable: true
          description: Restrict routing to providers with the requested execution region.
        required_data_region:
          type: string
          nullable: true
          description: Restrict routing to providers with the requested data region.
        require_zero_data_retention:
          type: boolean
          nullable: true
          description: Restrict routing to providers that support zero data retention.
        data_collection:
          type: string
          nullable: true
          enum:
            - allow
            - deny
        zdr:
          type: boolean
          nullable: true
        enforce_distillable_text:
          type: boolean
          nullable: true
        quantizations:
          type: array
          nullable: true
          items:
            type: string
        sort:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            Rank providers for this request, for example by price, latency, or
            throughput.
        max_price:
          type: object
          properties:
            prompt:
              oneOf:
                - type: number
                - type: string
            completion:
              oneOf:
                - type: number
                - type: string
            image:
              oneOf:
                - type: number
                - type: string
            audio:
              oneOf:
                - type: number
                - type: string
            request:
              oneOf:
                - type: number
                - type: string
        preferred_min_throughput:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
        preferred_max_latency:
          oneOf:
            - type: number
            - type: object
              additionalProperties:
                type: number
    BatchRequestCounts:
      type: object
      properties:
        total:
          type: integer
        completed:
          type: integer
        failed:
          type: integer
    AsyncWebhookPublicState:
      type: object
      description: >-
        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.
      properties:
        url:
          type: string
          format: uri
          nullable: true
        events:
          type: array
          items:
            type: string
        has_secret:
          type: boolean
        delivery:
          $ref: '#/components/schemas/AsyncWebhookDeliverySummary'
        attempts:
          type: array
          items:
            $ref: '#/components/schemas/AsyncWebhookDeliveryAttempt'
    BatchBillingSummary:
      type: object
      properties:
        currency:
          type: string
        billed:
          type: boolean
        charged:
          type: boolean
        reason:
          type: string
        state:
          type: string
          enum:
            - pending
            - estimated
            - settled
            - void
        reservation_id:
          type: string
          nullable: true
        reservation_status:
          type: string
          nullable: true
        estimated_provider_cost:
          type: string
          nullable: true
        estimated_user_cost:
          type: string
          nullable: true
        settled_provider_cost:
          type: string
          nullable: true
        settled_user_cost:
          type: string
          nullable: true
        estimated_nanos:
          type: integer
          nullable: true
        reserved_nanos:
          type: integer
          nullable: true
        estimation_truncated:
          type: boolean
          nullable: true
          description: >-
            True when the reservation estimate was scaled from a bounded sample
            of a larger batch input file.
        estimation_sample_size:
          type: integer
          nullable: true
          description: Number of input rows priced directly for the reservation estimate.
        estimation_total_rows:
          type: integer
          nullable: true
          description: Total input rows represented by the reservation estimate.
        total_nanos:
          type: integer
          nullable: true
        cost_nanos:
          type: integer
          nullable: true
        cost_usd:
          type: number
          nullable: true
        finalized_at:
          type: string
          nullable: true
        pricing_breakdown:
          type: object
          additionalProperties: true
    ErrorUpstreamError:
      type: object
      properties:
        code:
          type: string
          nullable: true
          example: PERMISSION_DENIED
        message:
          type: string
          nullable: true
          example: The caller does not have permission.
        description:
          type: string
          nullable: true
        param:
          type: string
          nullable: true
    ErrorFailureSampleItem:
      type: object
      properties:
        provider:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        upstream_error_code:
          type: string
          nullable: true
        upstream_error_message:
          type: string
          nullable: true
        upstream_error_description:
          type: string
          nullable: true
        upstream_error_param:
          type: string
          nullable: true
        upstream_payload_preview:
          type: string
          nullable: true
        retryable:
          type: boolean
          nullable: true
      additionalProperties: true
    ErrorProviderFailureDiagnostics:
      type: object
      properties:
        category:
          type: string
          enum:
            - credentials_not_configured
            - credentials_invalid_or_forbidden
            - provider_access_missing
            - region_or_project_restriction
            - model_unavailable_for_endpoint
            - rate_limited
            - server_error
        hint:
          type: string
        provider:
          type: string
          nullable: true
    ErrorRoutingDiagnostics:
      type: object
      properties:
        filterStages:
          type: array
          items:
            type: object
            properties:
              stage:
                type: string
              beforeCount:
                type: integer
              afterCount:
                type: integer
              droppedProviders:
                type: array
                items:
                  type: object
                  properties:
                    providerId:
                      type: string
                      nullable: true
                    reason:
                      type: string
                      nullable: true
                  additionalProperties: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderCandidateDiagnostics:
      type: object
      properties:
        totalProviders:
          type: integer
        supportsEndpointCount:
          type: integer
        candidateCount:
          type: integer
        droppedUnsupportedEndpoint:
          type: array
          items:
            type: string
        droppedMissingAdapter:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              endpoint:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderEnablementDiagnostics:
      type: object
      properties:
        capability:
          type: string
        providersBefore:
          type: array
          items:
            type: string
        providersAfter:
          type: array
          items:
            type: string
        dropped:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              reason:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    AsyncWebhookDeliverySummary:
      type: object
      description: >-
        Public delivery summary for gateway-managed async webhooks. Use this to
        distinguish job execution state from webhook delivery health.
      properties:
        total_attempts:
          type: integer
          description: Total delivery attempts recorded for this job.
        delivered_events:
          type: integer
          description: Number of delivery keys that have reached a delivered state.
        delivered_event_types:
          type: array
          description: Delivery keys that have been delivered at least once.
          items:
            type: string
          example:
            - video.completed
        pending_retries:
          type: integer
          description: Number of delivery keys currently scheduled for retry.
        next_retry_at:
          type: string
          nullable: true
          description: ISO timestamp for the next scheduled retry, when present.
        last_attempt_at:
          type: string
          nullable: true
          description: ISO timestamp for the most recent delivery attempt.
        last_attempt_status:
          type: string
          nullable: true
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
          description: Result of the most recent delivery attempt.
        last_response_status:
          type: integer
          nullable: true
          description: HTTP status returned by the webhook destination, when available.
        last_delivered_at:
          type: string
          nullable: true
          description: ISO timestamp for the most recent successful delivery.
        last_failure_at:
          type: string
          nullable: true
          description: ISO timestamp for the most recent failed or retrying attempt.
        last_error_message:
          type: string
          nullable: true
          description: Most recent delivery error message, when available.
    AsyncWebhookDeliveryAttempt:
      type: object
      description: Recent gateway-managed async webhook delivery attempt.
      properties:
        id:
          type: string
          description: Stable attempt identifier for audit and debugging.
        delivery_key:
          type: string
          description: Idempotency key for this event delivery.
          example: video.completed
        event_type:
          type: string
          description: Event type delivered to the webhook destination.
          example: video.completed
        status:
          type: string
          enum:
            - delivered
            - scheduled_retry
            - failed_permanently
        attempt_number:
          type: integer
          description: One-based attempt number for this delivery key.
        max_attempts:
          type: integer
          description: Maximum attempts before the delivery is marked failed permanently.
        tried_at:
          type: string
          description: ISO timestamp when this attempt was made.
        delivered_at:
          type: string
          nullable: true
          description: ISO timestamp when this attempt was delivered successfully.
        next_retry_at:
          type: string
          nullable: true
          description: ISO timestamp for the next retry after this attempt, when scheduled.
        response_status:
          type: integer
          nullable: true
          description: HTTP status returned by the webhook destination, when available.
        error_message:
          type: string
          nullable: true
          description: Delivery error message, when available.
        response_body_preview:
          type: string
          nullable: true
          description: Redacted response body preview from the webhook destination.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````