messages

Create Batch

Changed on

Submit a batch of agent runs for asynchronous processing.

Creates a job that will fan out messages to all listed agents and process them in parallel. The request will be rejected if it exceeds 256MB.

post/v1/messages/batches

Request

  • Base URL
    https://app.letta.com
  • URL
    https://app.letta.com/v1/messages/batches
  • Auth
    HTTP bearer

Request body

callback_urlstring uri nullable

Optional URL to call via POST when the batch completes. The callback payload will be a JSON object with the following fields: {'job_id': string, 'status': string, 'completed_at': string}. Where 'job_id' is the unique batch job identifier, 'status' is the final batch status (e.g., 'completed', 'failed'), and 'completed_at' is an ISO 8601 timestamp indicating when the batch job completed.

Response

Successful Response

created_by_idstring nullable

The id of the user that made this object.

last_updated_by_idstring nullable

The id of the user that made this object.

created_atstring date-time

The unix timestamp of when the job was created.

updated_atstring date-time nullable

The timestamp when the object was last updated.

status'created' | 'running' | 'completed' | 'failed' | 'pending' | 'cancelled' | 'expired'

Status of the job.

completed_atstring date-time nullable

The unix timestamp of when the job was completed.

stop_reason'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'
metadataobject nullable

The metadata of the job.

job_type'job' | 'run' | 'batch'
backgroundboolean nullable

Whether the job was created in background mode.

agent_idstring nullable

The agent associated with this job/run.

callback_urlstring nullable

If set, POST to this URL when the job completes.

callback_sent_atstring date-time nullable

Timestamp when the callback was last attempted.

callback_status_codeinteger nullable

HTTP status code returned by the callback endpoint.

callback_errorstring nullable

Optional error message from attempting to POST the callback endpoint.

ttft_nsinteger nullable

Time to first token for a run in nanoseconds

total_duration_nsinteger nullable

Total run duration in nanoseconds

idstring

The human-friendly ID of the Job

Example response

{
  "id": "job-123e4567-e89b-12d3-a456-426614174000"
}

Changes

  • f0554a0bf8b2Revision changes
    • info

      added the new optional request property /////////

    • info

      added the new optional request property /////////

    • info

      added the new optional request property /////////

  • 3a2d48137c08Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status