Create Agent Response

POST/v1/agentCreate Agent Response

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

Request body

required

application/json

objectResponsesRequest

ResponsesRequest

backgroundboolean

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.

inputvaluerequired

Input content - either a string or array of input items

Show child attributes

oneOf · 2 options

Option 1string

StringInput

Option 2array of value

InputItemArray

Show array items

oneOf · 3 options

Option 1objectInputMessage

InputMessage

contentvaluerequired

Message content - either a string or array of content parts

Show child attributes

oneOf · 2 options

Option 1string

StringContent

Option 2array of object

ContentPartArray

Show array items

image_urlstring

maxLength 2048

textstring

typestringrequired

one of "input_text", "input_image"

rolestringrequired

one of "user", "assistant", "system", "developer"

typestringrequired

one of "message"

Option 2objectFunctionCallOutputInput

FunctionCallOutputInput

call_idstringrequired

The call_id from function_call output

idnull | string

Replay metadata populated when this item was returned by the API.

namestring

Function name (required by some providers)

outputvaluerequired

Function result as a JSON string or an array of input_text and input_image content parts.

Show child attributes

oneOf · 2 options

Option 1string

StringOutput

Option 2array of value

OutputPartArray

Show array items

oneOf · 2 options

Option 1objectFunctionCallOutputTextPart

FunctionCallOutputTextPart

textstringrequired

typestringrequired

one of "input_text"

Option 2objectFunctionCallOutputImagePart

FunctionCallOutputImagePart

detailnull | string

Accepted for OpenAI replay compatibility; native tool-result forwarding ignores this hint.

one of "low", "high", "auto"

image_urlstringrequired

A fully qualified HTTP(S) URL or base64 image data URI.

typestringrequired

one of "input_image"

statusnull | string

Replay metadata populated when this item was returned by the API.

one of "in_progress", "completed", "incomplete"

thought_signaturestring

Base64-encoded signature from function_call

typestringrequired

one of "function_call_output"

Option 3objectFunctionCallInput

FunctionCallInput

argumentsstringrequired

Function arguments (JSON string)

call_idstringrequired

The call_id that correlates with function_call_output

namestringrequired

The function name

thought_signaturestring

Base64-encoded signature for thinking models

typestringrequired

one of "function_call"

instructionsstring

System instructions for the model

language_preferencestring

ISO 639-1 language code for response language

max_output_tokensinteger · 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.

minimum 1

max_stepsinteger · 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.

maximum 100 · minimum 1

modelstring

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.

modelsarray of 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.

maxItems 5 · minItems 1

Show child attributes

maxItems 5 · minItems 1

presetstring

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_idstring

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.

profilevalue

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

Show child attributes

allOf · 1 option

Option 1objectProfileReference

ProfileReference

idstringrequired

maxLength 128 · minLength 1

typestringrequired

one of "custom"

versionstring

Version to bind to, or "latest". Omitted means "latest".

reasoningobject

Show child attributes

effortstring

How much effort the model should spend on reasoning

one of "minimal", "low", "medium", "high", "xhigh", "max"

response_formatobject

Specifies the desired output format for the model response

Show child attributes

json_schemaobject

Defines a JSON schema for structured output validation

Show child attributes

descriptionstring

Optional description of the schema

namestringrequired

Name of the schema (1-64 alphanumeric chars)

maxLength 64 · minLength 1

schemaobjectrequired

The JSON schema object

strictboolean

Whether to enforce strict schema validation

typestringrequired

The type of response format

one of "json_schema"

skillsarray of value

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.

maxItems 16

Show child attributes

maxItems 16

Show array items

oneOf · 3 options

Option 1objectBuiltinSkill

BuiltinSkill

namestringrequired

Built-in skill to make available to the model. office is the full Office bundle (enables all four leaves). office/docx, office/pdf, office/pptx, office/xlsx each create polished documents of that type from scratch, with structural validation and visual QA.

one of "office", "office/docx", "office/pdf", "office/pptx", "office/xlsx"

typestringrequired

one of "builtin"

Option 2objectInlineSkill

InlineSkill

descriptionstringrequired

Short discovery description, limited to 1,024 UTF-8 bytes.

maxLength 1024 · minLength 1

instructionsstringrequired

Instructions returned by load_skill, limited to 65,536 UTF-8 bytes per skill and 262,144 bytes across the request.

maxLength 65536 · minLength 1

namestringrequired

Request-scoped lowercase ASCII name separated by single hyphens.

maxLength 64 · minLength 1 · pattern ^[a-z0-9]+(?:-[a-z0-9]+)*$

typestringrequired

one of "inline"

Option 3objectCustomSkill

CustomSkill

idstringrequired

Identifier of an organization-owned skill stored in Perplexity, in the form skill_<id>.

maxLength 128 · minLength 1

typestringrequired

one of "custom"

versionstring

Revision to load, or "latest". Omitted means "latest".

storeboolean

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.

streamboolean

If true, returns SSE stream instead of JSON

temperaturenumber · double

OpenAI-compatible sampling temperature forwarded to generation.

maximum 2 · minimum 0

toolsarray of value

Tools available to the model

Show child attributes

Show array items

oneOf · 8 options

Option 1objectWebSearchTool

WebSearchTool

Web search tool configuration for the Responses API

filtersvalue

Show child attributes

allOf · 2 options

Option 1objectSearchDomainFilter

SearchDomainFilter

search_domain_filterarray of string

Limit search results to specific domains (max 20)

maxItems 20

Show child attributes

maxItems 20

Option 2objectDateFilters

DateFilters

last_updated_after_filterstring

Input: MM/DD/YYYY, Output: YYYY-MM-DD

last_updated_before_filterstring

Input: MM/DD/YYYY, Output: YYYY-MM-DD

search_after_date_filterstring

Input: MM/DD/YYYY, Output: YYYY-MM-DD

search_before_date_filterstring

Input: MM/DD/YYYY, Output: YYYY-MM-DD

search_recency_filterstring

Time-based recency filter for search results

one of "hour", "day", "week", "month", "year"

max_resultsinteger · int32

Upper bound on the number of search results collected per call. Must be between 1 and 50; values outside that range are rejected with a 400 error.

maximum 50 · minimum 1

max_tokensinteger · int32

Maximum total tokens for search context

max_tokens_per_pageinteger · int32

Maximum tokens to extract per search result page

search_context_sizestring

Named search context budget. Explicit max_tokens / max_tokens_per_page budgets override it.

one of "low", "medium", "high"

search_typestring

Search type for this tool. `web` uses standard web search. `fast` uses the lower-latency Fast Search path, billed at $1.00 per 1,000 invocations plus model tokens. When omitted, inherits the preset's search type if configured; otherwise uses `web`.

one of "web", "fast"

typestringrequired

Tool type identifier

one of "web_search"

user_locationobject

User's geographic location for search personalization

Show child attributes

citystring

City name

countrystring

ISO 3166-1 alpha-2 country code

latitudenumber · double

Latitude coordinate

longitudenumber · double

Longitude coordinate

regionstring

State or region name

Option 2objectFinanceSearchTool

FinanceSearchTool

Finance search tool configuration for the Agent API

typestringrequired

Tool type identifier

one of "finance_search"

Option 3objectPeopleSearchTool

PeopleSearchTool

People search tool configuration for the Agent API

typestringrequired

Tool type identifier

one of "people_search"

Option 4objectFetchUrlTool

FetchUrlTool

max_urlsinteger · int32

Maximum number of URLs to fetch per tool call

maximum 10 · minimum 1

typestringrequired

one of "fetch_url"

Option 5objectFunctionTool

FunctionTool

descriptionstring

A description of what the function does

namestringrequired

The name of the function

parametersobject

JSON Schema defining the function's parameters

strictboolean

Whether to enable strict schema validation

typestringrequired

one of "function"

Option 6objectSandboxTool

SandboxTool

Sandbox tool configuration for the Responses API. Executes code in an isolated container during an Agent API request.

typestringrequired

Tool type identifier

one of "sandbox"

Option 7objectMcpTool

McpTool

Connects a user-supplied remote MCP server. Agent API discovers the server's tools when the request starts and calls them like native tools. Matches OpenAI's mcp tool. `defer_loading: true` keeps discovered definitions out of the initial model context and lets the model search, inspect, and call them as needed. `require_approval` and `connector_id` are ignored: every call auto-runs, and only bring-your-own `server_url` is honored.

allowed_toolsarray of string

Optional allowlist of tool names. Empty exposes all discovered tools.

Show child attributes

authorizationstring

An access token passed to the remote MCP server for authentication. Provide the raw token value. Never logged or echoed.

defer_loadingboolean

When true, keeps discovered tool definitions out of the initial model context and lets the model load relevant schemas as needed. Defaults to false.

headersobject

Extra request headers.

server_labelstringrequired

Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the server's tools.

server_urlstringrequired

HTTPS URL of the remote MCP server. Must be a Streamable HTTP MCP endpoint; the legacy SSE transport is not supported.

typestringrequired

one of "mcp"

Option 8objectConnectorTool

ConnectorTool

A Perplexity-managed connector scoped to the authenticated API organization.

allowed_toolsarray of string

Optional exact-name allowlist. Omitted or empty admits every live tool.

Show child attributes

idstringrequired

Opaque connector identifier.

server_descriptionstring

Optional model-facing namespace description.

server_labelstringrequired

Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the connector's tools.

typestringrequired

one of "connector"

top_pnumber · double

OpenAI-compatible nucleus sampling parameter forwarded to generation.

maximum 1 · minimum 0

Example request

{
  "background": true,
  "input": "string",
  "instructions": "string",
  "language_preference": "string",
  "max_output_tokens": 0,
  "max_steps": 0,
  "model": "string",
  "models": [
    "string"
  ],
  "preset": "string",
  "previous_response_id": "string",
  "profile": {
    "id": "string",
    "type": "custom",
    "version": "string"
  },
  "reasoning": {
    "effort": "high"
  },
  "response_format": {
    "json_schema": {
      "description": "string",
      "name": "string",
      "schema": {
        "additionalProp1": null
      },
      "strict": true
    },
    "type": "json_schema"
  },
  "skills": [
    {
      "name": "office",
      "type": "builtin"
    }
  ],
  "store": true,
  "stream": true,
  "temperature": 0,
  "tools": [
    {
      "allowed_tools": [
        "string"
      ],
      "id": "string",
      "server_description": "string",
      "server_label": "string",
      "type": "connector"
    }
  ],
  "top_p": 0
}

Responses

objectResponsesResponse

ResponsesResponse

Non-streaming response returned when stream is false

created_atinteger · int64required

Unix timestamp when the response was created

errorobject

Error information returned when a request fails

Show child attributes

codestring

Error code

messagestringrequired

Human-readable error message

typestring

Error type category

idstringrequired

Unique identifier for the response

modelstringrequired

Model used for generation

objectstringrequired

Object type in API responses

one of "response"

outputarray of valuerequired

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

Show child attributes

Show array items

oneOf · 10 options

Option 1objectMessageOutputItem

MessageOutputItem

contentarray of objectrequired

Show child attributes

Show array items

annotationsarray of object

Show child attributes

Show array items

Text annotation (URL citation)

end_indexinteger · int32

End character index of the annotated text

start_indexinteger · int32

Start character index of the annotated text

titlestring

Title of the cited source

typestring

Annotation type (url_citation)

urlstring

URL of the cited source

textstringrequired

typestringrequired

Type of a content part

one of "output_text"

idstringrequired

rolestringrequired

Role in a message

one of "assistant"

statusstringrequired

Status of a response or output item

one of "completed", "failed", "incomplete", "in_progress", "queued", "cancelled"

typestringrequired

one of "message"

Option 2objectSearchResultsOutputItem

SearchResultsOutputItem

queriesarray of string

Show child attributes

resultsarray of objectrequired

Show child attributes

Show array items

A single search result used in LLM responses

datestring

Publication date of the result

idinteger · int64required

Unique numeric identifier for the result

last_updatedstring

Date the result was last updated

snippetstringrequired

Text snippet from the search result

sourcestring

Source of search results

one of "web"

titlestringrequired

Title of the search result page

urlstringrequired

URL of the search result page

typestringrequired

one of "search_results"

Option 3objectFetchUrlResultsOutputItem

FetchUrlResultsOutputItem

contentsarray of objectrequired

Show child attributes

Show array items

Content fetched from a URL

snippetstringrequired

The fetched content snippet

titlestringrequired

The title of the page

urlstringrequired

The URL from which content was fetched

typestringrequired

one of "fetch_url_results"

Option 4objectFinanceResultsOutputItem

FinanceResultsOutputItem

Intermediate output item emitted when the finance_search tool runs. One item is emitted per tool invocation; the requested categories and tickers are echoed at the envelope level alongside the per-result entries.

categoriesarray of string

Finance categories the tool was asked to retrieve for this invocation (for example, "quote").

Show child attributes

resultsarray of objectrequired

Structured finance results returned for the invocation.

Show child attributes

Show array items

A single structured finance result returned by the finance_search tool.

categorystringrequired

Finance category this result belongs to (for example, "quote").

contentstringrequired

Structured content for the result, typically a markdown-formatted table or snippet.

sourcesarray of string

Source URLs backing the structured content.

Show child attributes

tickersarray of string

Ticker symbols this result pertains to.

Show child attributes

tickersarray of string

Ticker symbols the tool was asked to retrieve for this invocation.

Show child attributes

typestringrequired

one of "finance_results"

Option 5objectPeopleSearchResultsOutputItem

PeopleSearchResultsOutputItem

Intermediate output item emitted when the people_search tool runs. Mirrors the shape of search_results: the agent's generated queries plus a list of per-person result entries.

queriesarray of string

Search queries the agent generated for this people_search invocation.

Show child attributes

resultsarray of objectrequired

Per-person result entries. Shape matches SearchResult (id, url, title, snippet, source, last_updated).

Show child attributes

Items: SearchResult ↑

typestringrequired

one of "people_search_results"

Option 6objectFunctionCallOutputItem

FunctionCallOutputItem

argumentsstringrequired

JSON string of arguments

call_idstringrequired

Correlates with function_call_output input

idstringrequired

namestringrequired

statusstringrequired

Status of a response or output item

one of "completed", "failed", "incomplete", "in_progress", "queued", "cancelled"

thought_signaturestring

Base64-encoded opaque signature for thinking models

typestringrequired

one of "function_call"

Option 7objectSandboxResultsOutputItem

SandboxResultsOutputItem

Result of a sandbox tool invocation. Contains the executed code and its output.

codestring

The code that was executed inside the sandbox.

duration_msinteger · int64

Wall-clock duration of the sandbox execution, in milliseconds.

exit_codeinteger · int32

Process exit code. Non-zero indicates a runtime error.

statusstringrequired

Execution status. One of `completed`, `timed_out`, `failed`.

one of "completed", "timed_out", "failed"

stderrstring

Standard error captured from the sandbox execution.

stdoutstring

Standard output captured from the sandbox execution.

typestringrequired

one of "sandbox_results"

Option 8objectMcpListToolsOutputItem

McpListToolsOutputItem

Tools discovered on one external MCP server when the request starts. Matches OpenAI's mcp_list_tools item.

connector_idstring

Present only when the item originated from a managed connector.

errorstring

Present only when the server's tools could not be listed. Absent on success.

idstringrequired

server_labelstringrequired

toolsarray of objectrequired

Show child attributes

Show array items

One tool discovered on a remote MCP server.

descriptionstring

input_schemaobjectrequired

The server's JSON Schema for the tool, passed through unmodified.

namestringrequired

typestringrequired

one of "mcp_list_tools"

Option 9objectMcpCallOutputItem

McpCallOutputItem

One tool call executed against an external MCP server, modeled on OpenAI's mcp_call item.

argumentsstringrequired

JSON-encoded arguments the model passed.

connector_idstring

Present only when the item originated from a managed connector.

errornull | string

The failure string when the call failed (also returned to the model in-band); null on success, matching OpenAI's mcp_call.

idstringrequired

namestringrequired

outputstring

Tool output text; empty when the call failed.

server_labelstringrequired

typestringrequired

one of "mcp_call"

Option 10objectToolSearchOutputItem

ToolSearchOutputItem

Complete public definitions matched by one hosted external-tool search.

argumentsstring

Exact argument text authored by the model for hosted search.

call_idnull | stringrequired

Always null for hosted search.

executionstringrequired

Execution location. Currently `server`. Clients must tolerate unknown values.

idstringrequired

statusstringrequired

Current execution status. Known values are `in_progress`, `completed`, and `incomplete`. Clients must tolerate unknown values.

toolsarray of objectrequired

Show child attributes

Show array items

A response-only namespace containing complete external tool definitions.

descriptionstringrequired

namestringrequired

toolsarray of objectrequired

Show child attributes

Show array items

One function definition discovered by hosted external-tool search.

descriptionstring

namestringrequired

parametersobject

The server's JSON Schema for the tool, passed through unmodified.

typestringrequired

one of "function"

typestringrequired

one of "namespace"

typestringrequired

one of "tool_search_output"

statusstringrequired

Status of a response or output item

one of "completed", "failed", "incomplete", "in_progress", "queued", "cancelled"

usageobject

Token usage and cost information for a Responses API request

Show child attributes

costobject

Cost breakdown for a Responses API request

Show child attributes

cache_creation_costnumber · double

Cost for cache creation in USD

cache_read_costnumber · double

Cost for cache reads in USD

currencystringrequired

Currency code for cost values

one of "USD"

input_costnumber · doublerequired

Cost for input tokens in USD

output_costnumber · doublerequired

Cost for output tokens in USD

tool_calls_costnumber · double

Cost for tool call invocations in USD

total_costnumber · doublerequired

Total cost for the request in USD

input_tokensinteger · int64required

Number of input tokens used

input_tokens_detailsobject

Show child attributes

cache_creation_input_tokensinteger · int64

Tokens used for cache creation

cache_read_input_tokensinteger · int64

Tokens read from cache

output_tokensinteger · int64required

Number of output tokens generated

tool_calls_detailsobject

Details about tool call invocations

total_tokensinteger · int64required

Total tokens used (input + output)

valueResponseStreamEvent

ResponseStreamEvent

SSE stream event. Discriminate by the `type` field: - `response.created`: Initial response object - `response.in_progress`: Response processing started - `response.completed`: Final response with output - `response.failed`: Error occurred - `response.output_item.added`: New output item started - `response.output_item.done`: Output item completed - `response.output_text.delta`: Streaming text delta - `response.output_text.done`: Final text content - `response.reasoning.started`: Reasoning phase started - `response.reasoning.search_queries`: Search queries issued - `response.reasoning.search_results`: Search results received - `response.reasoning.fetch_url_queries`: URL fetch queries issued - `response.reasoning.fetch_url_results`: URL fetch results received - `response.reasoning.stopped`: Reasoning phase complete

oneOf · 14 options

Option 1objectResponseCreatedEvent

ResponseCreatedEvent

Response created event (type: "response.created"). Contains the initial response object.

responseobject

Non-streaming response returned when stream is false

Show child attributes

created_atinteger · int64required

Unix timestamp when the response was created

errorobjectErrorInfo ↑

Error information returned when a request fails

idstringrequired

Unique identifier for the response

modelstringrequired

Model used for generation

objectstringrequired

Object type in API responses

one of "response"

outputarray of valuerequired

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

Show child attributes

Items: OutputItem ↑

statusstringrequired

Status of a response or output item

one of "completed", "failed", "incomplete", "in_progress", "queued", "cancelled"

usageobjectResponsesUsage ↑

Token usage and cost information for a Responses API request

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

typestringrequired

SSE event type discriminator

one of "response.created", "response.in_progress", "response.completed", "response.failed", "response.output_item.added", "response.output_item.done", "response.output_text.delta", "response.output_text.done", "response.reasoning.started", "response.reasoning.search_queries", "response.reasoning.search_results", "response.reasoning.fetch_url_queries", "response.reasoning.fetch_url_results", "response.reasoning.stopped"

Option 2objectResponseInProgressEvent

ResponseInProgressEvent

Response in progress event (type: "response.in_progress"). Emitted when response processing has started.

responseobjectResponsesResponse ↑

Non-streaming response returned when stream is false

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

typestringrequired

SSE event type discriminator

Option 3objectResponseCompletedEvent

ResponseCompletedEvent

Response event Contains the full or partial response object.

responseobjectResponsesResponse ↑

Non-streaming response returned when stream is false

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

typestringrequired

SSE event type discriminator

Option 4objectResponseFailedEvent

ResponseFailedEvent

Response failed event (type: "response.failed"). Contains error details when streaming fails.

errorobjectrequiredErrorInfo ↑

Error information returned when a request fails

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

typestringrequired

SSE event type discriminator

Option 5objectOutputItemAddedEvent

OutputItemAddedEvent

Output item added event (type: "response.output_item.added"). Emitted when a new output item (message or tool call) starts.

itemvaluerequiredOutputItem ↑

output_indexinteger · int64required

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

typestringrequired

SSE event type discriminator

Option 6objectOutputItemDoneEvent

OutputItemDoneEvent

Output item done event (type: "response.output_item.done"). Emitted when an output item (message or tool call) completes.

itemvaluerequiredOutputItem ↑

output_indexinteger · int64required

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

typestringrequired

SSE event type discriminator

Option 7objectTextDeltaEvent

TextDeltaEvent

Text delta event (type: "response.output_text.delta"). Contains incremental text content.

content_indexinteger · int64required

deltastringrequired

item_idstringrequired

output_indexinteger · int64required

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

typestringrequired

SSE event type discriminator

Option 8objectTextDoneEvent

TextDoneEvent

Text done event (type: "response.output_text.done"). Contains the final text content.

content_indexinteger · int64required

item_idstringrequired

output_indexinteger · int64required

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

textstringrequired

typestringrequired

SSE event type discriminator

Option 9objectReasoningStartedEvent

ReasoningStartedEvent

Reasoning started event (type: "response.reasoning.started"). Signals the model has started reasoning/searching.

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

thoughtstring

typestringrequired

SSE event type discriminator

Option 10objectSearchQueriesEvent

SearchQueriesEvent

Search queries event (type: "response.reasoning.search_queries"). Contains search queries being executed.

queriesarray of stringrequired

Show child attributes

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

thoughtstring

typestringrequired

SSE event type discriminator

Option 11objectSearchResultsEvent

SearchResultsEvent

Search results event (type: "response.reasoning.search_results"). Contains search results returned.

resultsarray of objectrequired

Show child attributes

Items: SearchResult ↑

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

thoughtstring

typestringrequired

SSE event type discriminator

usageobjectResponsesUsage ↑

Token usage and cost information for a Responses API request

Option 12objectFetchUrlQueriesEvent

FetchUrlQueriesEvent

URL fetch queries event (type: "response.reasoning.fetch_url_queries"). Contains URLs being fetched.

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

thoughtstring

typestringrequired

SSE event type discriminator

urlsarray of stringrequired

Show child attributes

Option 13objectFetchUrlResultsEvent

FetchUrlResultsEvent

URL fetch results event (type: "response.reasoning.fetch_url_results"). Contains fetched URL contents.

contentsarray of objectrequired

Show child attributes

Items: UrlContent ↑

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

thoughtstring

typestringrequired

SSE event type discriminator

Option 14objectReasoningStoppedEvent

ReasoningStoppedEvent

Reasoning stopped event (type: "response.reasoning.stopped"). Signals the model has finished reasoning/searching.

sequence_numberinteger · int64required

Monotonically increasing sequence number for event ordering

thoughtstring

typestringrequired

SSE event type discriminator

Example response

{
  "created_at": 0,
  "error": {
    "code": "string",
    "message": "string",
    "type": "string"
  },
  "id": "string",
  "model": "string",
  "object": "response",
  "output": [
    {
      "contents": [
        {
          "snippet": "string",
          "title": "string",
          "url": "string"
        }
      ],
      "type": "fetch_url_results"
    }
  ],
  "status": "cancelled",
  "usage": {
    "cost": {
      "cache_creation_cost": 0,
      "cache_read_cost": 0,
      "currency": "USD",
      "input_cost": 0,
      "output_cost": 0,
      "tool_calls_cost": 0,
      "total_cost": 0
    },
    "input_tokens": 0,
    "input_tokens_details": {
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 0
    },
    "output_tokens": 0,
    "tool_calls_details": {
      "additionalProp1": {
        "invocation": 0
      }
    },
    "total_tokens": 0
  }
}

object

errorobjectErrorInfo ↑

Error information returned when a request fails

Example response

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

Examples

curl -X POST 'https://api.perplexity.ai/v1/agent' \
  -H 'Content-Type: application/json' \
  -d '{"background":true,"input":"string","instructions":"string","language_preference":"string","max_output_tokens":0,"max_steps":0,"model":"string","models":["string"],"preset":"string","previous_response_id":"string","profile":{"id":"string","type":"custom","version":"string"},"reasoning":{"effort":"high"},"response_format":{"json_schema":{"description":"string","name":"string","schema":{"additionalProp1":null},"strict":true},"type":"json_schema"},"skills":[{"name":"office","type":"builtin"}],"store":true,"stream":true,"temperature":0,"tools":[{"allowed_tools":["string"],"id":"string","server_description":"string","server_label":"string","type":"connector"}],"top_p":0}'

const response = await fetch('https://api.perplexity.ai/v1/agent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"background":true,"input":"string","instructions":"string","language_preference":"string","max_output_tokens":0,"max_steps":0,"model":"string","models":["string"],"preset":"string","previous_response_id":"string","profile":{"id":"string","type":"custom","version":"string"},"reasoning":{"effort":"high"},"response_format":{"json_schema":{"description":"string","name":"string","schema":{"additionalProp1":null},"strict":true},"type":"json_schema"},"skills":[{"name":"office","type":"builtin"}],"store":true,"stream":true,"temperature":0,"tools":[{"allowed_tools":["string"],"id":"string","server_description":"string","server_label":"string","type":"connector"}],"top_p":0}),
});
const data = await response.json();

const response = await fetch('https://api.perplexity.ai/v1/agent', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"background\":true,\"input\":\"string\",\"instructions\":\"string\",\"language_preference\":\"string\",\"max_output_tokens\":0,\"max_steps\":0,\"model\":\"string\",\"models\":[\"string\"],\"preset\":\"string\",\"previous_response_id\":\"string\",\"profile\":{\"id\":\"string\",\"type\":\"custom\",\"version\":\"string\"},\"reasoning\":{\"effort\":\"high\"},\"response_format\":{\"json_schema\":{\"description\":\"string\",\"name\":\"string\",\"schema\":{\"additionalProp1\":null},\"strict\":true},\"type\":\"json_schema\"},\"skills\":[{\"name\":\"office\",\"type\":\"builtin\"}],\"store\":true,\"stream\":true,\"temperature\":0,\"tools\":[{\"allowed_tools\":[\"string\"],\"id\":\"string\",\"server_description\":\"string\",\"server_label\":\"string\",\"type\":\"connector\"}],\"top_p\":0}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.perplexity.ai/v1/agent",
    headers={"Content-Type": "application/json"},
    data='{"background":true,"input":"string","instructions":"string","language_preference":"string","max_output_tokens":0,"max_steps":0,"model":"string","models":["string"],"preset":"string","previous_response_id":"string","profile":{"id":"string","type":"custom","version":"string"},"reasoning":{"effort":"high"},"response_format":{"json_schema":{"description":"string","name":"string","schema":{"additionalProp1":null},"strict":true},"type":"json_schema"},"skills":[{"name":"office","type":"builtin"}],"store":true,"stream":true,"temperature":0,"tools":[{"allowed_tools":["string"],"id":"string","server_description":"string","server_label":"string","type":"connector"}],"top_p":0}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"background":true,"input":"string","instructions":"string","language_preference":"string","max_output_tokens":0,"max_steps":0,"model":"string","models":["string"],"preset":"string","previous_response_id":"string","profile":{"id":"string","type":"custom","version":"string"},"reasoning":{"effort":"high"},"response_format":{"json_schema":{"description":"string","name":"string","schema":{"additionalProp1":null},"strict":true},"type":"json_schema"},"skills":[{"name":"office","type":"builtin"}],"store":true,"stream":true,"temperature":0,"tools":[{"allowed_tools":["string"],"id":"string","server_description":"string","server_label":"string","type":"connector"}],"top_p":0}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.perplexity.ai/v1/agent", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://api.perplexity.ai/v1/agent");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"background\":true,\"input\":\"string\",\"instructions\":\"string\",\"language_preference\":\"string\",\"max_output_tokens\":0,\"max_steps\":0,\"model\":\"string\",\"models\":[\"string\"],\"preset\":\"string\",\"previous_response_id\":\"string\",\"profile\":{\"id\":\"string\",\"type\":\"custom\",\"version\":\"string\"},\"reasoning\":{\"effort\":\"high\"},\"response_format\":{\"json_schema\":{\"description\":\"string\",\"name\":\"string\",\"schema\":{\"additionalProp1\":null},\"strict\":true},\"type\":\"json_schema\"},\"skills\":[{\"name\":\"office\",\"type\":\"builtin\"}],\"store\":true,\"stream\":true,\"temperature\":0,\"tools\":[{\"allowed_tools\":[\"string\"],\"id\":\"string\",\"server_description\":\"string\",\"server_label\":\"string\",\"type\":\"connector\"}],\"top_p\":0}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.perplexity.ai/v1/agent"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"background\":true,\"input\":\"string\",\"instructions\":\"string\",\"language_preference\":\"string\",\"max_output_tokens\":0,\"max_steps\":0,\"model\":\"string\",\"models\":[\"string\"],\"preset\":\"string\",\"previous_response_id\":\"string\",\"profile\":{\"id\":\"string\",\"type\":\"custom\",\"version\":\"string\"},\"reasoning\":{\"effort\":\"high\"},\"response_format\":{\"json_schema\":{\"description\":\"string\",\"name\":\"string\",\"schema\":{\"additionalProp1\":null},\"strict\":true},\"type\":\"json_schema\"},\"skills\":[{\"name\":\"office\",\"type\":\"builtin\"}],\"store\":true,\"stream\":true,\"temperature\":0,\"tools\":[{\"allowed_tools\":[\"string\"],\"id\":\"string\",\"server_description\":\"string\",\"server_label\":\"string\",\"type\":\"connector\"}],\"top_p\":0}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.perplexity.ai/v1/agent")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"background\":true,\"input\":\"string\",\"instructions\":\"string\",\"language_preference\":\"string\",\"max_output_tokens\":0,\"max_steps\":0,\"model\":\"string\",\"models\":[\"string\"],\"preset\":\"string\",\"previous_response_id\":\"string\",\"profile\":{\"id\":\"string\",\"type\":\"custom\",\"version\":\"string\"},\"reasoning\":{\"effort\":\"high\"},\"response_format\":{\"json_schema\":{\"description\":\"string\",\"name\":\"string\",\"schema\":{\"additionalProp1\":null},\"strict\":true},\"type\":\"json_schema\"},\"skills\":[{\"name\":\"office\",\"type\":\"builtin\"}],\"store\":true,\"stream\":true,\"temperature\":0,\"tools\":[{\"allowed_tools\":[\"string\"],\"id\":\"string\",\"server_description\":\"string\",\"server_label\":\"string\",\"type\":\"connector\"}],\"top_p\":0}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.perplexity.ai/v1/agent");
request.Content = new StringContent("{\"background\":true,\"input\":\"string\",\"instructions\":\"string\",\"language_preference\":\"string\",\"max_output_tokens\":0,\"max_steps\":0,\"model\":\"string\",\"models\":[\"string\"],\"preset\":\"string\",\"previous_response_id\":\"string\",\"profile\":{\"id\":\"string\",\"type\":\"custom\",\"version\":\"string\"},\"reasoning\":{\"effort\":\"high\"},\"response_format\":{\"json_schema\":{\"description\":\"string\",\"name\":\"string\",\"schema\":{\"additionalProp1\":null},\"strict\":true},\"type\":\"json_schema\"},\"skills\":[{\"name\":\"office\",\"type\":\"builtin\"}],\"store\":true,\"stream\":true,\"temperature\":0,\"tools\":[{\"allowed_tools\":[\"string\"],\"id\":\"string\",\"server_description\":\"string\",\"server_label\":\"string\",\"type\":\"connector\"}],\"top_p\":0}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "created_at": 0,
  "error": {
    "code": "string",
    "message": "string",
    "type": "string"
  },
  "id": "string",
  "model": "string",
  "object": "response",
  "output": [
    {
      "contents": [
        {
          "snippet": "string",
          "title": "string",
          "url": "string"
        }
      ],
      "type": "fetch_url_results"
    }
  ],
  "status": "cancelled",
  "usage": {
    "cost": {
      "cache_creation_cost": 0,
      "cache_read_cost": 0,
      "currency": "USD",
      "input_cost": 0,
      "output_cost": 0,
      "tool_calls_cost": 0,
      "total_cost": 0
    },
    "input_tokens": 0,
    "input_tokens_details": {
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 0
    },
    "output_tokens": 0,
    "tool_calls_details": {
      "additionalProp1": {
        "invocation": 0
      }
    },
    "total_tokens": 0
  }
}

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

Search documentation

Skills

Operations

Create Agent Response

Request body

Responses

Skills

Operations