Public API

Public API reference for the Batchwork client, jobs, models, server primitives, stores, helpers, and typed error types.

Import the supported surface from batchwork. Server and store names are also available from batchwork.server and batchwork.stores.

Client

`Batchwork`

The async client accepts optional credentials, http_client, media_resolver, and timeout arguments. Prefer async with Batchwork() as client; an injected HTTPX client remains caller-owned.

Method	Return behavior
`await batch(model, requests, ...)`	`BatchJob` for text/messages
`await batch_embeddings(model, requests, ...)`	`BatchJob` for embeddings
`await batch_images(model, requests, ...)`	`BatchJob` for images
`await get_batch(ref)`	Resumed `BatchJob`
`get_batch_results(ref)`	Async iterator of `BatchResult`
`await cancel_batch(ref)`	`None`
`await aclose()`	Closes client-owned resources

get_batch_results() is consumed with async for; do not await it directly.

Jobs

BatchJob exposes id, provider, status, request_counts, and snapshot. The state properties reflect the latest cached snapshot.

Method	Return behavior
`await poll()`	Fresh `BatchSnapshot`
`await wait(poll_interval=15, timeout=None, on_poll=None)`	Terminal `BatchSnapshot`
`results()`	Async iterator of `BatchResult`
`await collect()`	`list[BatchResult]`
`await cancel()`	Snapshot retrieved after requesting cancellation

wait() itself returns an awaitable. poll_interval must be a positive finite number; timeout must be finite and non-negative when provided. Invalid values raise ValueError, while timeout expiration raises BatchTimeoutError. See Jobs and Results for lifecycle details.

wait() retries transient provider status reads within its local deadline. Direct poll() calls remain single-attempt operations.

Models and providers

String models require provider/model form. gemini aliases google, and togetherai aliases together. String xAI models use ModelKind.RESPONSES; other providers default to ModelKind.CHAT.

ModelSpec selects provider, model_id, and an explicit ModelKind of CHAT, RESPONSES, or COMPLETION. See Configuration for examples and the supported modality matrix.

Requests and configuration

BatchRequest accepts exactly one of prompt or messages, plus generation settings inherited from BatchRequestSettings (BatchDefaults).
BatchEmbeddingRequest extends BatchEmbeddingRequestSettings with value and optional custom_id. Embedding settings include canonical optional dimensions and provider options; BatchEmbeddingDefaults applies those settings only when a request omits them.
BatchImageRequest and BatchImageDefaults configure provider-supported image batches.
ProviderCredentials contains an API key, base URL, and headers.
BatchLimits bounds request count, serialized request bytes, and upload bytes.

Messages use SystemMessage, UserMessage, AssistantMessage, and ToolMessage. Content types include TextPart, ImagePart, FilePart, reasoning parts, tool-call/result parts, approval parts, and custom provider-defined parts.

Tools use FunctionTool or ProviderDefinedTool, with ToolChoice, NamedToolChoice, and ProviderToolChoice controlling selection. Tool outputs include text, JSON, errors, execution denial, content, files, and custom output parts.

All public models are frozen, reject unknown fields, and accept snake_case or camelCase input.

Batchwork submissions validate canonical settings and provider options against the selected provider before upload. The lower-level builders in batchwork.body retain their explicit strict control for compatibility; the public client does not expose a permissive validation mode.

Results and state

BatchSnapshot contains provider status, counts, timestamps, and raw state.
BatchResult contains custom_id, normalized status, raw response, and any normalized text, embedding, images, usage, or error.
BatchRef identifies an existing batch without retaining a client.
BatchImage, BatchUsage, BatchRequestCounts, and BatchResultError describe normalized output details.

State names include BatchProvider, BatchStatus, BatchResultStatus, and the exported TERMINAL_STATUSES constant.

Media

DefaultMediaResolver implements the default local-file, HTTPS, and inline-media policy. Raw strings are classified as HTTP(S), data URL, strict base64, then a path relative to its configured base directory. Applications may inject a MediaResolver; successful resolutions return ResolvedMedia. ProviderFileReference and tagged file-data types represent provider-owned or explicitly typed media sources. See Security for file, SSRF, redirect, and size boundaries.

Server and stores

The server surface includes BatchPoller, TrackTarget, TrackedBatch, TickResult, TickFailure, BatchWebhookEvent, WebhookResponse, callback and credential protocols, signed-webhook helpers, replay-store protocols, URL validation, and PinnedWebhookTransport.

Stores include BatchStore, MemoryBatchStore, RedisBatchStore, create_memory_store(), and create_redis_store(). See Polling and webhooks, Stores, and Security.

Helpers

resolve_model() parses a string model or returns an existing ModelSpec.
provider_from_ref() identifies the provider represented by a BatchRef.
is_terminal_status() tests whether a status is terminal.
coerce_credentials() validates a credential mapping.
utc_datetime() converts a Unix timestamp to an aware UTC datetime.

Errors

BatchworkError is the package base error and covers request validation, provider HTTP failures, and provider results that are not ready. Narrower exported errors include:

BatchTimeoutError: wait() exceeded its timeout.
BatchClosedError: an operation used a closed client or job.
UnsupportedProviderError: unknown provider or unsupported modality.
MissingDependencyError: an optional integration is unavailable.
MediaResolutionError: remote or inline media could not be resolved safely.
BatchStateError: exported for invalid batch-state operations.

Invalid wait() timing arguments raise the standard ValueError, not a BatchworkError subclass.