GET

/v1/schemas/perplexity/chat/v1/agent?kind=output

kind outputactivity chathash b269cbf6…extracted Nov 17, 2026version currentsource upstream spec ↗

Response body

9 properties · 6 required · 39 $defs
propertytypedescriptionconstraints
created_at*integerUnix timestamp when the response was createdformat: int64
id*stringUnique identifier for the response
model*stringModel used for generation
object*enumObject type identifierresponse
output*OutputItem[]Array of output items (messages, search results, tool calls)
status*enumStatus of the responsecompleted | failed | incomplete | in_progress | queued | cancelled
errorErrorInfoError information returned when a request failsnullable
effortstringEffort and version that ran this response, as `name@<version>` (e.g., "fast@2026-09-29.0"). Present only when the request used an effort level. Streams resumed with `starting_after` omit it. For an alias, this is the effort and version that the alias selects. …
usageResponsesUsageToken usage and cost information for a Responses API requestnullable

Types

39 $defs

Annotationobject

Text annotation (URL citation)

end_indexintegerEnd character index of the annotated textformat: int32
start_indexintegerStart character index of the annotated textformat: int32
titlestringTitle of the cited source
typestringAnnotation type (url_citation)
urlstringURL of the cited source

ContentPartobject

annotationsAnnotation[]
text*string
type*enumType of a content partoutput_text

ContentPartTypeenum

Type of a content part

output_text

Currencyenum

Currency code for cost values

USD

ErrorInfoobject

Error information returned when a request fails

codestringError code
message*stringHuman-readable error message
typestringError type category

FetchUrlResultsOutputItemobject

contents*UrlContent[]
type*enumfetch_url_results

FinanceResultobject

A single structured finance result returned by the finance_search tool.

category*stringFinance category this result belongs to (for example, "quote").
content*stringStructured content for the result, typically a markdown-formatted table or snippet.
sourcesstring[]Source URLs backing the structured content.
tickersstring[]Ticker symbols this result pertains to.

FinanceResultsOutputItemobject

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.

categoriesstring[]Finance categories the tool was asked to retrieve for this invocation (for example, "quote").
results*FinanceResult[]Structured finance results returned for the invocation.
tickersstring[]Ticker symbols the tool was asked to retrieve for this invocation.
type*enumfinance_results

FunctionCallOutputItemobject

arguments*stringJSON string of arguments
call_id*stringCorrelates with function_call_output input
id*string
name*string
status*enumStatus of a response or output itemcompleted | failed | incomplete | in_progress | queued | cancelled
thought_signaturestringBase64-encoded opaque signature for thinking models
type*enumfunction_call

ImageResultobject

A single image search result

image_url*stringURL of the image
origin_url*stringOriginal URL where the image was found
height*integerHeight of the image in pixelsformat: int64
width*integerWidth of the image in pixelsformat: int64
titlestringTitle or description of the image

ImageSearchResultsOutputItemobject

errorstringPresent when image search failed. The value is image_search_failed.
queriesstring[]
results*ImageResult[]
type*enumimage_search_results

InputTokensDetailsobject

cached_tokens*integerformat: int64
cache_creation_input_tokensintegerformat: int64
cache_read_input_tokensintegerformat: int64

McpApprovalRequestOutputItemobject

One MCP or connector tool call waiting for the application to approve or deny it. The call has not run. Answer with an `mcp_approval_response` input item in the next request.

type*enummcp_approval_request
id*stringOpaque approval request ID. Return it as `approval_request_id` when submitting a decision.
server_label*string
connector_idstringPresent only when the item originated from a connector.
name*string
arguments*stringJSON-encoded arguments the model proposed.
thought_signaturestringBase64-encoded signature for thinking models. Resend it unchanged in manual history.

McpCallOutputItemobject

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

type*enummcp_call
id*string
server_label*string
connector_idstringPresent only when the item originated from a managed connector.
name*string
arguments*stringJSON-encoded arguments the model passed.
outputstringTool output text; empty when the call failed.
erroranyThe failure string when the call failed (also returned to the model in-band); null on success, matching OpenAI's mcp_call.
approval_request_idanyThe `mcp_approval_request` ID this call resolved; null when the call ran automatically.

McpListToolsOutputItemobject

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

type*enummcp_list_tools
id*string
server_label*string
connector_idstringPresent only when the item originated from a managed connector.
tools*McpToolDef[]
errorstringPresent only when the server's tools could not be listed. Absent on success.

McpToolDefobject

One tool discovered on a remote MCP server.

name*string
descriptionstring
input_schema*objectThe server's JSON Schema for the tool, passed through unmodified.
annotationsobjectTool annotations. `read_only` is untrusted catalog metadata used by approval filters, not a side-effect guarantee.

MessageOutputItemobject

content*ContentPart[]
id*string
role*enumRole in a messageassistant
status*enumStatus of a response or output itemcompleted | failed | incomplete | in_progress | queued | cancelled
type*enummessage

NamespaceToolobject

A response-only namespace containing complete external tool definitions.

type*enumnamespace
name*string
description*string
tools*NamespaceToolDef[]

NamespaceToolDefobject

One function definition discovered by hosted external-tool search.

type*enumfunction
name*string
descriptionstring
parametersobjectThe server's JSON Schema for the tool, passed through unmodified.

OutputItemMessageOutputItem | SearchResultsOutputItem | ImageSearchResultsOutputItem | …

OutputTokensDetailsobject

reasoning_tokens*integerformat: int64

PeopleSearchResultsOutputItemobject

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.

queriesstring[]Search queries the agent generated for this people_search invocation.
results*SearchResult[]Per-person result entries. Shape matches SearchResult (id, url, title, snippet, source, last_updated).
type*enumpeople_search_results

ResponsesCostobject

Cost breakdown for a Responses API request

cache_creation_costnumberCost for cache creation in USDformat: double
cache_read_costnumberCost for cache reads in USDformat: double
currency*enumCurrency of the cost valuesUSD
input_cost*numberCost for input tokens in USDformat: double
output_cost*numberCost for output tokens in USDformat: double
tool_calls_costnumberCost for tool call invocations in USDformat: double
tool_calls_cost_detailsobjectUSD cost attributed to each reported tool by tool name. Unpriced reported tools are included with a value of 0.
total_cost*numberTotal cost for the request in USDformat: double

ResponsesObjectTypeenum

Object type in API responses

response

ResponsesUsageobject

Token usage and cost information for a Responses API request

costResponsesCostCost breakdown for the request
input_tokens*integerNumber of input tokens usedformat: int64
input_tokens_detailsobject
output_tokens*integerNumber of output tokens generatedformat: int64
tool_calls_detailsobjectDetails about tool call invocations
total_tokens*integerTotal tokens used (input + output)format: int64

RoleTypeenum

Role in a message

assistant

SandboxReadFileOutputItemobject

Result of a file read inside the sandbox.

type*enumsandbox_read_file
call_id*stringIdentifier of the tool call that produced this item.
file_path*stringPath of the file the sandbox read.
contentstringText read from the file.
start_lineintegerLine number where `content` starts. Present only when the read covered part of the file.format: int32
total_linesintegerNumber of lines in the file. Present only when the read covered part of the file.format: int32
errorstringError message if the read failed.

SandboxResultsOutputItemobject

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

type*enumsandbox_results
codestringThe code that was executed inside the sandbox.
stdoutstringStandard output captured from the sandbox execution.
stderrstringStandard error captured from the sandbox execution.
exit_codeintegerProcess exit code. Non-zero indicates a runtime error.format: int32
duration_msintegerWall-clock duration of the sandbox execution, in milliseconds.format: int64
status*enumExecution status. One of `completed`, `timed_out`, `failed`.completed | timed_out | failed

SandboxWriteFileOutputItemobject

Result of a file write inside the sandbox.

type*enumsandbox_write_file
call_id*stringIdentifier of the tool call that produced this item.
file_path*stringPath of the file the sandbox wrote.
size_bytesintegerSize of the written file, in bytes.format: int64
errorstringError message if the write failed.

SearchResultobject

A single search result used in LLM responses

datestringPublication date of the result
id*integerUnique numeric identifier for the resultformat: int64
last_updatedstringDate the result was last updated
snippet*stringText snippet from the search result
sourceenumSource type of the resultweb
title*stringTitle of the search result page
url*stringURL of the search result page

SearchResultsOutputItemobject

queriesstring[]
results*SearchResult[]
type*enumsearch_results

SearchSourceenum

Source of search results

web

ShareFileOutputItemobject

Result of a `share_file` tool call. On success, `file_id` and `filename` identify a sandbox file you can download with the response files endpoints.

type*enumshare_file
call_id*stringIdentifier of the tool call that produced this item.
file_idstringIdentifier of the shared file.
filenamestringName of the shared file.
size_bytesintegerSize of the shared file, in bytes.format: int64
urlstringRelative path for downloading the file's content.
errorstringError message if the file could not be shared.

SkillLoadedOutputItemobject

Records that the model loaded a skill during the run.

type*enumskill_loaded
name*stringName of the loaded skill.

Statusenum

Status of a response or output item

completed | failed | incomplete | in_progress | queued | cancelled

ToolCallDetailsobject

Details about a tool call invocation

invocationintegerNumber of times this tool was invokedformat: int64
cost_usdnumberAccumulated customer charge in USD for this tool when the API can attribute one directly.format: double
token_usageToolCallTokenUsage[]Model token usage for tools backed by internal LLM calls. Sandbox SDK usage is aggregated by model.

ToolCallTokenUsageobject

modelstringModel identifier reported by the internal LLM call.
input_tokens*integerTotal input tokens, including uncached, cache write, and cache read tokens.format: int64
output_tokens*integerOutput tokens returned by the internal LLM call.format: int64
input_tokens_details*InputTokensDetails
output_tokens_details*OutputTokensDetails

ToolSearchOutputItemobject

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

type*enumtool_search_output
id*string
call_id*anyAlways null for hosted search.
execution*stringExecution location. Currently `server`. Clients must tolerate unknown values.
argumentsstringExact argument text authored by the model for hosted search.
tools*NamespaceTool[]
status*stringCurrent execution status. Known values are `in_progress`, `completed`, and `incomplete`. Clients must tolerate unknown values.

UrlContentobject

Content fetched from a URL

snippet*stringThe fetched content snippet
title*stringThe title of the page
url*stringThe URL from which content was fetched

Validate a payload

before you spend tokens
shell
$ curl -X POST https://modelschemas.com/v1/validate \
    -d '{"provider":"perplexity","endpointId":"v1/agent","payload":{…}}'
→ {"valid": false, "errors": [{"path": "#", "keyword": "required", …}]}