Give Feedback

pydo.batches.create()

Generated on 3 Aug 2026 from pydo version v0.40.0

Copy page as Markdown View page as Markdown

Usage

client.batches.create(
    file_id=os.environ["BATCH_INPUT_FILE_ID"],
    provider="openai",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    request_id=str(uuid.uuid4()),
)

Returns JSONRaises HttpResponseError

Serverless inference methods can authenticate with a model access key instead of a DigitalOcean API token:

client = Client(token=os.environ.get("MODEL_ACCESS_KEY"))

Description

Submits a batch job against a previously uploaded JSONL input file. The upload must have completed before this call; otherwise the request is rejected.

Supply a unique request_id to make the submission idempotent — retries with the same value return the existing job. When provider is openai, the url on each JSONL line must match endpoint.

Parameters

file_id string required

Example: a1b2c3d4-e5f6-4789-90ab-cdef12345678

The file_id returned by POST /v1/batches/files.

provider string required

The inference provider whose JSONL schema the input file conforms to. openai follows the OpenAI Batch API input schema (custom_id, method, url, body); anthropic follows the Anthropic Message Batches JSONL conventions.

One of: openai, anthropic

endpoint string optional

Inference endpoint each request is dispatched to. **Required when provider is openai and must match the url on every JSONL line. Must be omitted when provider is anthropic.**

One of: /v1/responses, /v1/chat/completions

completion_window string required

Example: 24h

Time window in which the job must complete. Jobs that do not finish in time transition to expired.

Default: 24h

request_id string required

Example: c7e3ad1e-20c3-4e47-9bf2-6f2a4d6a2f11

Client-supplied idempotency key. Retries with the same value return the existing job instead of creating a duplicate.

metadata object or null optional

Example: {'team': 'ml-eval', 'dataset': 'prompts_v1'}

Optional string-valued metadata to attach to the job.

Request Sample

Show Request Sample

import os
import uuid

from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

batch = client.batches.create(
    file_id=os.environ["BATCH_INPUT_FILE_ID"],
    provider="openai",
    endpoint="/v1/chat/completions",
    completion_window="24h",
    request_id=str(uuid.uuid4()),
)

print("batch_id:", batch.get("batch_id"))
print("status:  ", batch.get("status"))

Response Example

Show Response Example

{
  "batch_id": "0e9d1d35-3d1e-4d66-9a2f-8c7e0f6b3e21",
  "status": "in_progress",
  "provider": "openai",
  "endpoint": "/v1/chat/completions",
  "completion_window": "24h",
  "input_file_id": "a1b2c3d4-e5f6-4789-90ab-cdef12345678",
  "output_file_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "error_file_id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "request_counts": {
    "total": 10000,
    "completed": 0,
    "failed": 0
  },
  "request_id": "c7e3ad1e-20c3-4e47-9bf2-6f2a4d6a2f11",
  "errors": [
    {
      "code": "invalid_input_file",
      "message": "Line 42: missing required field 'custom_id'.",
      "line": 42
    }
  ],
  "created_at": "2026-04-24T19:19:19Z",
  "in_progress_at": "2026-04-24T19:20:05Z",
  "finalizing_at": "2026-04-24T20:10:42Z",
  "completed_at": "2026-04-24T20:15:30Z",
  "expires_at": "2026-04-25T19:19:19Z",
  "cancelled_at": "2026-04-24T19:45:11Z",
  "failed_at": "2026-04-24T19:50:00Z"
}

More Information

See /v1/batches in the API reference for additional detail on responses, headers, parameters, and more.