Sign in

v36

latestOpenAPI 3.1.0raw.githubusercontent.com2025-10-091882241.2 MB
agents

Send Message Async

Asynchronously process a user message and return a run object. The actual processing happens in the background, and the status can be checked using the run ID.

This is "asynchronous" in the sense that it's a background run and explicitly must be fetched by the run ID.

post/v1/agents/{agent_id}/messages/async

Path parameters

agent_idstring required

Request body

max_stepsinteger

Maximum number of steps the agent should take to process the request.

use_assistant_messageboolean

Whether the server should parse specific tool call arguments (default send_message) as AssistantMessage objects.

assistant_message_tool_namestring

The name of the designated message tool.

assistant_message_tool_kwargstring

The name of the message argument in the designated message tool.

include_return_message_typesMessageType[] nullable

Only return specified message types in the response. If None (default) returns all messages.

enable_thinkingstring

If set to True, enables reasoning before responses or tool calls from the agent.

callback_urlstring nullable

Optional callback URL to POST to when the job completes

Response

Successful Response

idstring

The human-friendly ID of the Run

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

Status of the run.

created_atstring date-time

The timestamp when the run was created.

completed_atstring date-time nullable

The timestamp when the run was completed.

agent_idstring required

The unique identifier of the agent associated with the run.

backgroundboolean nullable

Whether the run was created in background mode.

metadataobject nullable

Additional metadata for the run.

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

If set, POST to this URL when the run 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

Example response

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