Give Feedback

pydo.batches.cancel()

Generated on 3 Aug 2026 from pydo version v0.40.0

Copy page as Markdown View page as Markdown

Usage

client.batches.cancel(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

Requests cancellation of a batch job. The job transitions to cancelling and, once in-flight requests drain, to cancelled. Jobs already in a terminal state (completed, failed, expired, cancelled) cannot be cancelled and return 409 Conflict. Cancellation is also rejected with 409 Conflict while the job has not yet been submitted to the upstream provider — there is nothing to cancel until the provider batch id is assigned.

Partial results produced before cancellation remain available via GET /v1/batches/{batch_id}/results.

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"))

result = client.batches.cancel(os.environ["BATCH_ID"])

print("batch_id:    ", result.get("batch_id"))
print("status:      ", result.get("status"))
print("cancelled_at:", result.get("cancelled_at"))

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