Create Agent Response

POST

/

v1

/

agent

Create Agent Response

curl --request POST \
  --url https://api.perplexity.ai/v1/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": "<string>",
  "instructions": "<string>"
}
'

{
  "created_at": 123,
  "id": "<string>",
  "model": "<string>",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "text": "<string>",
          "type": "output_text",
          "annotations": [
            {
              "end_index": 123,
              "start_index": 123,
              "title": "<string>",
              "type": "<string>",
              "url": "<string>"
            }
          ]
        }
      ],
      "id": "<string>",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "status": "completed",
  "error": {
    "message": "<string>",
    "code": "<string>",
    "type": "<string>"
  },
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "cost": {
      "currency": "USD",
      "input_cost": 123,
      "output_cost": 123,
      "total_cost": 123,
      "cache_creation_cost": 123,
      "cache_read_cost": 123,
      "tool_calls_cost": 123
    },
    "input_tokens_details": {
      "cache_creation_input_tokens": 123,
      "cache_read_input_tokens": 123
    },
    "tool_calls_details": {}
  }
}

{
  "error": {
    "message": "<string>",
    "code": "<string>",
    "type": "<string>"
  }
}

Authorization

string

header

required

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

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. For requests that specify model or models without a preset, the default is 1. Set max_steps to at least 3 when using finance_search with a direct model so the agent has enough steps to initialize and run the tool. 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.6-terra", "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.

profile

ProfileReference · object

Saved, versioned configuration to run with. The version is resolved when the request is admitted. Cannot be combined with preset.

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 | ConnectorTool · object)[]

Tools available to the model

Web search tool configuration for the Responses API

skills

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

Built-in, request-scoped inline, and organization-owned custom 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

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 | ToolSearchOutputItem · 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

Was this page helpful?

⌘I