Batches

Create a Message Batch

client.messages.batches.create(, ?): MessageBatch

POST/v1/messages/batches

Retrieve a Message Batch

client.messages.batches.retrieve(, ?): MessageBatch

GET/v1/messages/batches/{message_batch_id}

List Message Batches

client.messages.batches.list(?, ?): Page<MessageBatch>

GET/v1/messages/batches

Cancel a Message Batch

client.messages.batches.cancel(, ?): MessageBatch

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

Delete a Message Batch

client.messages.batches.delete(, ?): DeletedMessageBatch

DELETE/v1/messages/batches/{message_batch_id}

Retrieve Message Batch results

client.messages.batches.results(, ?): MessageBatchIndividualResponse | Stream<MessageBatchIndividualResponse>

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

Models

DeletedMessageBatch { id, type }

id: string

ID of the Message Batch.

type: "message_batch_deleted"

Deleted object type.

For Message Batches, this is always "message_batch_deleted".

defaultmessage_batch_deleted

MessageBatch { id, archived_at, cancel_initiated_at, 7 more }

MessageBatchCanceledResult { type }

type: "canceled"

defaultcanceled

MessageBatchErroredResult { error, type }

error: ErrorResponse { error, request_id, type }

error: ErrorObject

One of the following:

request_id: string | null

type: "error"

defaulterror

type: "errored"

defaulterrored

MessageBatchExpiredResult { type }

type: "expired"

defaultexpired

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: string

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:

MessageBatchRequestCounts { canceled, errored, expired, 2 more }

canceled: number

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: number

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: number

Number of requests in the Message Batch that have expired.

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

default0

processing: number

Number of requests in the Message Batch that are processing.

default0

succeeded: number

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

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

default0

MessageBatchResult = MessageBatchSucceededResult { message, type } | MessageBatchErroredResult { error, type } | MessageBatchCanceledResult { type } | MessageBatchExpiredResult { type }

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:

MessageBatchSucceededResult { message, type }

message: Message { id, container, content, 7 more }

type: "succeeded"

defaultsucceeded