Give Feedback

pydo.batches.retrieve()

Generated on 1 Oct 2026 from pydo version v0.43.0

Copy page as Markdown View page as Markdown

Usage

client.batches.retrieve(os.environ["BATCH_ID"])

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

Returns the current state of a batch job. Poll until status reaches a terminal value (completed, failed, expired, or cancelled).

Parameters

batch_id string required: The batch job identifier.

Request Sample

Show Request Sample

import os

from pydo import Client

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

batch = client.batches.retrieve(os.environ["BATCH_ID"])

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

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/{batch_id} in the API reference for additional detail on responses, headers, parameters, and more.