Sign in

Create Response

Generate a response for the provided input with optional web search and reasoning.

post/v1/responses

Request body

instructionsstring

System instructions for the model

language_preferencestring

ISO 639-1 language code for response language

max_output_tokensinteger

Maximum tokens to generate

max_stepsinteger

Maximum number of research loop steps. If provided, overrides the preset's max_steps value. Must be >= 1 if specified. Maximum allowed is 10.

modelstring

Model ID in provider/model format (e.g., "xai/grok-4-1", "openai/gpt-4o"). If models is also provided, models takes precedence. Required if neither models nor preset is provided.

modelsstring[]

Model fallback chain. Each model is in provider/model format. Models are tried in order until one succeeds. Max 5 models allowed. If set, takes precedence over single model field. The response.model will reflect the model that actually succeeded.

presetstring

Preset configuration name (e.g., "sonar-pro", "sonar-reasoning"). Pre-configured model with system prompt and search parameters. Required if model is not provided.

streamboolean

If true, returns SSE stream instead of JSON

backgroundboolean nullable

Run the response asynchronously. When true, the request is queued and the response object's status will be queued or in_progress. Poll GET /v1/responses/{response_id} to retrieve the final result.

Response

Successful response. Content type depends on stream parameter:

  • stream: false (default): application/json with Response
  • stream: true: text/event-stream with SSE events
created_atinteger required
idstring required
modelstring required
object'response' required

Object type in API responses

status'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action' required

Status of a response or output item

backgroundboolean

Whether the response was created in background mode.

Changes