Skip to main content
POST
Create Agent Response

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
input
required

Input content - either a string or array of input items

background
boolean

Run the response asynchronously. With stream: false, the request returns immediately with status: "queued"; poll GET /v1/responses/{id} until the response reaches a terminal status. Background runs are durable, so you can also stream them and reconnect after a drop.

instructions
string

System instructions for the model

language_preference
string

ISO 639-1 language code for response language

max_output_tokens
integer<int32>

Maximum tokens to generate. This is a shared optional Agent API request parameter, but it is required when using anthropic/* models. If omitted for an Anthropic model, the API returns HTTP 400 with: validation failed: max_output_tokens is required when using Anthropic models.

Required range: x >= 1
max_steps
integer<int32>

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

Required range: 1 <= x <= 100
model
string

Model ID in provider/model format (e.g., "openai/gpt-5", "anthropic/claude-sonnet-4-6"). If models is also provided, models takes precedence. Required if neither models nor preset is provided.

models
string[]

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.

Required array length: 1 - 5 elements
preset
string

Preset configuration name (e.g., "fast", "low", "medium", "high", "xhigh"). Pre-configured model with system prompt and search parameters. Required if model is not provided.

previous_response_id
string

OpenAI-compatible previous response id for multi-turn response chains. When set, the new response continues from the completed prior response's saved state. The prior response must belong to the same account and have completed.

reasoning
ReasoningConfig · object
response_format
ResponseFormat · object

Specifies the desired output format for the model response

store
boolean

OpenAI-compatible storage toggle. When false, the response is hidden from later retrieve calls, and the echoed response reports store: false. It can still be used as a previous_response_id continuation source.

stream
boolean

If true, returns SSE stream instead of JSON

tools
(WebSearchTool · object | FinanceSearchTool · object | PeopleSearchTool · object | FetchUrlTool · object | FunctionTool · object | SandboxTool · object | McpTool · object)[]

Tools available to the model

Web search tool configuration for the Responses API

skills
(BuiltinSkill · object | InlineSkill · object)[]

Built-in and request-scoped inline skills available to the model. Skill metadata is disclosed to the model up front; full instructions are loaded on demand through the load_skill tool. Selecting any skill enables the sandbox tool for the request. Requests with skills run on the durable backend and skills are not echoed back on Response objects.

Maximum array length: 16
temperature
number<double>

OpenAI-compatible sampling temperature forwarded to generation.

Required range: 0 <= x <= 2
top_p
number<double>

OpenAI-compatible nucleus sampling parameter forwarded to generation.

Required range: 0 <= x <= 1

Response

Successful response. Content type depends on stream parameter:

  • stream: false (default): application/json with Response
  • stream: true: text/event-stream with SSE events

Non-streaming response returned when stream is false

created_at
integer<int64>
required

Unix timestamp when the response was created

id
string
required

Unique identifier for the response

model
string
required

Model used for generation

object
enum<string>
required

Object type identifier

Available options:
response
output
(MessageOutputItem · object | SearchResultsOutputItem · object | FetchUrlResultsOutputItem · object | FinanceResultsOutputItem · object | PeopleSearchResultsOutputItem · object | FunctionCallOutputItem · object | SandboxResultsOutputItem · object | McpListToolsOutputItem · object | McpCallOutputItem · object)[]
required

Array of output items (messages, search results, tool calls)

status
enum<string>
required

Status of the response

Available options:
completed,
failed,
incomplete,
in_progress,
queued,
cancelled
error
ErrorInfo · object

Error details if the response failed

usage
ResponsesUsage · object

Token usage and cost information