POST/v1/batches

Create a batch

Runs an uploaded JSONL file asynchronously. Every line's body.model must be a batch model, a slug ending in -batch (for example gpt-6-luna-batch); other models are rejected per line with not_batch_callable. One batch runs on one provider.

Rejected lines are listed in errors and skipped; the job fails only when every line is rejected. completion_window is accepted and always reads 24h.

Authentication: Bearer API key in the Authorization header

Request body

  • input_file_idstringrequired

    The id of a file uploaded with purpose: batch.

  • endpointenumrequired

    The API every line calls. Which ones a model supports depends on its provider.

    "/v1/chat/completions""/v1/responses""/v1/messages"
  • completion_windowstring

    Accepted for compatibility and ignored; always 24h.

  • metadataobject

    Your own labels. Values are stored as strings.

Responses

  • 200

    The new batch, status validating.

    Response
    • idstring
    • objectstring
    • endpointstring
    • errorsobject | null

      Rejected input lines: {object: list, data: [{code, message, line, custom_id}]}.

    • input_file_idstring
    • completion_windowstring
    • statusenum
      "validating""in_progress""finalizing""completed""failed""expired""cancelling""cancelled"
    • output_file_idstring | null
    • error_file_idstring | null
    • created_atinteger
    • expires_atinteger | null
    • completed_atinteger | null
    • failed_atinteger | null
    • expired_atinteger | null
    • cancelled_atinteger | null
    • request_countsobject

      Accepted lines only; rejected lines are in errors.

      request_counts
      • totalinteger
      • completedinteger
      • failedinteger
    • metadataobject | null
  • 400

    The upload or batch was rejected; the message names the line or field.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 401

    The key is missing, malformed, expired or revoked.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"
  • 402

    Your credits cannot cover the batch reservation.

    Response
    • errorobject
      error
      • messagestring

        What went wrong and how to fix it.

      • typestring

        For example invalid_request_error, authentication_error, permission_error, rate_limit_error, insufficient_quota, api_error.

      • codestring

        The stable error code.

      • paramstring | null

        The request field at fault, when there is one.

      • refusal_reasonenum

        Present only on code: refusal.

        "cyber_policy""cbrn""content_policy""recitation""data_inspection""unspecified"

Request

curl https://api.experientiallabs.ai/v1/batches \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input_file_id": "file_3f9a1c0e7b2d4a6f8e1c2b3d", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'

Response

{
  "id": "batch_9c2e4b7a1f0d3e6c5b8a2d4f",
  "object": "batch",
  "endpoint": "/v1/chat/completions",
  "errors": null,
  "input_file_id": "file_3f9a1c0e7b2d4a6f8e1c2b3d",
  "completion_window": "24h",
  "status": "validating",
  "output_file_id": null,
  "error_file_id": null,
  "created_at": 1795132800,
  "expires_at": 1795219200,
  "completed_at": null,
  "failed_at": null,
  "expired_at": null,
  "cancelled_at": null,
  "request_counts": {
    "total": 2,
    "completed": 0,
    "failed": 0
  },
  "metadata": {
    "job": "nightly"
  }
}

https://api.experientiallabs.ai/v1/batches