View Source Anthropic.Batches (anthropic_community v0.5.0)

The Batches resource (Message Batches API): submit up to 100k Messages.create/2-shaped requests for asynchronous, discounted bulk processing.

Example

{:ok, batch} =
  Anthropic.Batches.create(client, [
    %{custom_id: "request-1", params: [model: "claude-opus-4-8", max_tokens: 100, messages: [%{role: "user", content: "Hi"}]]},
    %{custom_id: "request-2", params: [model: "claude-opus-4-8", max_tokens: 100, messages: [%{role: "user", content: "Hello"}]]}
  ])

{:ok, batch} = Anthropic.Batches.retrieve(client, batch.id)

if batch.processing_status == "ended" do
  {:ok, results} = Anthropic.Batches.results(client, batch)
end

Summary

Types

batch()

batch_request()

deleted_batch()

list_result()

result()

Functions

cancel(client, batch_id)

Cancels a batch that is still processing.

create(client, requests)

Creates a message batch from a list of %{custom_id:, params:} requests.

delete(client, batch_id)

Deletes a batch's tracking data. The batch must first be in an ended state (cannot delete an in-progress batch).

list(client, opts \\ [])

Lists batches, most recently created first.

list_all(client, opts \\ [])

Like list/2, but returns a lazy Stream of individual batches that transparently fetches subsequent pages as it's consumed, instead of one page at a time.

results(client, batch_id)

Fetches and parses the JSONL results of an ended batch, matched by custom_id. Accepts either a batch id or a batch() map already carrying results_url (avoids an extra retrieve/2 round-trip).

retrieve(client, batch_id)

Retrieves a batch by id.

Types

batch()

@type batch() :: %{
  id: String.t(),
  type: String.t(),
  processing_status: String.t(),
  request_counts: map(),
  results_url: String.t() | nil,
  created_at: String.t() | nil,
  ended_at: String.t() | nil,
  expires_at: String.t() | nil
}

batch_request()

@type batch_request() :: %{
  custom_id: String.t(),
  params: Anthropic.Messages.create_opts()
}

deleted_batch()

@type deleted_batch() :: %{id: String.t(), type: String.t()}

list_result()

@type list_result() :: %{
  data: [batch()],
  has_more: boolean(),
  first_id: String.t() | nil,
  last_id: String.t() | nil
}

result()

@type result() :: %{
  custom_id: String.t(),
  type: String.t(),
  message: Anthropic.Messages.Message.t() | nil,
  error: Anthropic.Error.t() | nil
}

Functions

cancel(client, batch_id)

@spec cancel(Anthropic.Client.t(), batch_id :: String.t()) ::
  {:ok, batch()} | {:error, Anthropic.Error.t()}

Cancels a batch that is still processing.

create(client, requests)

@spec create(Anthropic.Client.t(), [batch_request()]) ::
  {:ok, batch()} | {:error, Anthropic.Error.t()}

Creates a message batch from a list of %{custom_id:, params:} requests.

delete(client, batch_id)

@spec delete(Anthropic.Client.t(), batch_id :: String.t()) ::
  {:ok, deleted_batch()} | {:error, Anthropic.Error.t()}

Deletes a batch's tracking data. The batch must first be in an ended state (cannot delete an in-progress batch).

list(client, opts \\ [])

@spec list(Anthropic.Client.t(),
  before_id: String.t(),
  after_id: String.t(),
  limit: pos_integer()
) ::
  {:ok, list_result()} | {:error, Anthropic.Error.t()}

Lists batches, most recently created first.

list_all(client, opts \\ [])

@spec list_all(Anthropic.Client.t(),
  before_id: String.t(),
  after_id: String.t(),
  limit: pos_integer()
) ::
  Enumerable.t()

Like list/2, but returns a lazy Stream of individual batches that transparently fetches subsequent pages as it's consumed, instead of one page at a time.

results(client, batch_id)

@spec results(Anthropic.Client.t(), batch() | String.t()) ::
  {:ok, [result()]} | {:error, Anthropic.Error.t()}

Fetches and parses the JSONL results of an ended batch, matched by custom_id. Accepts either a batch id or a batch() map already carrying results_url (avoids an extra retrieve/2 round-trip).

retrieve(client, batch_id)

@spec retrieve(Anthropic.Client.t(), batch_id :: String.t()) ::
  {:ok, batch()} | {:error, Anthropic.Error.t()}

Retrieves a batch by id.