Batches

Create a Message Batch

messages.batches.create(**kwargs) -> MessageBatch

POST/v1/messages/batches

Send a batch of Message creation requests.

Retrieve a Message Batch

messages.batches.retrieve(message_batch_id, **kwargs) -> MessageBatch

GET/v1/messages/batches/{message_batch_id}

This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the results_url field in the response.

List Message Batches

messages.batches.list(**kwargs) -> SyncPage[MessageBatch]

GET/v1/messages/batches

List all Message Batches within a Workspace. Most recently created batches are returned first.

Cancel a Message Batch

messages.batches.cancel(message_batch_id, **kwargs) -> MessageBatch

POST/v1/messages/batches/{message_batch_id}/cancel

Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a canceling state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.

Delete a Message Batch

messages.batches.delete(message_batch_id, **kwargs) -> DeletedMessageBatch

DELETE/v1/messages/batches/{message_batch_id}

Retrieve Message Batch results

messages.batches.results(message_batch_id, **kwargs) -> MessageBatchIndividualResponse

GET/v1/messages/batches/{message_batch_id}/results

Streams the results of a Message Batch as a .jsonl file.

Models

class DeletedMessageBatch: type: "message_batch_deleted"; id

type: Literal["message_batch_deleted"]

Deleted object type.

For Message Batches, this is always "message_batch_deleted".

defaultmessage_batch_deleted

id: str

ID of the Message Batch.

class MessageBatch: type: "message_batch"; id; archived_at; ... # 7 more

class MessageBatchCanceledResult: type: "canceled"

type: Literal["canceled"]

defaultcanceled

class MessageBatchErroredResult: type: "errored"; error

type: Literal["errored"]

defaulterrored

error: ErrorResponse

type: Literal["error"]

defaulterror

error: ErrorObject

One of the following:

request_id: Optional[str]

class MessageBatchExpiredResult: type: "expired"

type: Literal["expired"]

defaultexpired

class MessageBatchIndividualResponse: custom_id; result

This is a single line in the response .jsonl file and does not represent the response as a whole.

custom_id: str

Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.

Must be unique for each request within the Message Batch.

result: MessageBatchResult

Processing result for this request.

Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.

One of the following:

class MessageBatchRequestCounts: canceled; errored; expired; ... # 2 more

canceled: int

Number of requests in the Message Batch that have been canceled.

This is zero until processing of the entire Message Batch has ended.

default0

errored: int

Number of requests in the Message Batch that encountered an error.

This is zero until processing of the entire Message Batch has ended.

default0

expired: int

Number of requests in the Message Batch that have expired.

This is zero until processing of the entire Message Batch has ended.

default0

processing: int

Number of requests in the Message Batch that are processing.

default0

succeeded: int

Number of requests in the Message Batch that have completed successfully.

This is zero until processing of the entire Message Batch has ended.

default0

type MessageBatchResult = ...

Processing result for this request.

Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.

One of the following:

class MessageBatchSucceededResult: type: "succeeded"; message

type: Literal["succeeded"]

defaultsucceeded

message: Message