GET

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

Accept:

kind outputactivity chathash 3d0f19ee…extracted Oct 23, 2026version currentsource upstream spec ↗

field	recorded source
schema	Source linked above. upstream-spec Source trace `aefcebc5a1ccb9e8efbd21c6018dad997312757832b29e4654372167a3e4fef3` { "fetchedAt": 1792732871, "extractorVersion": "1", "verifiedAt": null }

Response body

9 properties · 6 required · 35 $defs

property	type	description	constraints
created_at*	integer	Unix timestamp when the response was created	format: int64
id*	string	Unique identifier for the response
model*	string	Model used for generation
object*	enum	Object type identifier	response
output*	OutputItem[]	Array of output items (messages, search results, tool calls)
status*	enum	Status of the response	completed \| failed \| incomplete \| in_progress \| queued \| cancelled
error	ErrorInfo	Error details if the response failed
effort	string	Effort 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. …
usage	ResponsesUsage	Token usage and cost information

Types

35 $defs

Annotationobject

Text annotation (URL citation)

end_index	integer	End character index of the annotated text	format: int32
start_index	integer	Start character index of the annotated text	format: int32
title	string	Title of the cited source
type	string	Annotation type (url_citation)
url	string	URL of the cited source

ContentPartobject

annotations	Annotation[]
text*	string
type*	enum	Type of a content part	output_text

ErrorInfoobject

Error information returned when a request fails

code	string	Error code
message*	string	Human-readable error message
type	string	Error type category

FetchUrlResultsOutputItemobject

contents*	UrlContent[]
type*	enum		fetch_url_results

FinanceResultobject

A single structured finance result returned by the finance_search tool.

category*	string	Finance category this result belongs to (for example, "quote").
content*	string	Structured content for the result, typically a markdown-formatted table or snippet.
sources	string[]	Source URLs backing the structured content.
tickers	string[]	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.

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

FunctionCallOutputItemobject

arguments*	string	JSON string of arguments
call_id*	string	Correlates with function_call_output input
id*	string
name*	string
status*	enum	Status of a response or output item	completed \| failed \| incomplete \| in_progress \| queued \| cancelled
thought_signature	string	Base64-encoded opaque signature for thinking models
type*	enum		function_call

ImageResultobject

A single image search result

image_url*	string	URL of the image
origin_url*	string	Original URL where the image was found
height*	integer	Height of the image in pixels	format: int64
width*	integer	Width of the image in pixels	format: int64
title	string	Title or description of the image

ImageSearchResultsOutputItemobject

error	string	Present when image search failed. The value is image_search_failed.
queries	string[]
results*	ImageResult[]
type*	enum		image_search_results

InputTokensDetailsobject

cached_tokens*	integer	format: int64
cache_creation_input_tokens	integer	format: int64
cache_read_input_tokens	integer	format: 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*	enum		mcp_approval_request
id*	string	Opaque approval request ID. Return it as `approval_request_id` when submitting a decision.
server_label*	string
connector_id	string	Present only when the item originated from a connector.
name*	string
arguments*	string	JSON-encoded arguments the model proposed.
thought_signature	string	Base64-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*	enum		mcp_call
id*	string
server_label*	string
connector_id	string	Present only when the item originated from a managed connector.
name*	string
arguments*	string	JSON-encoded arguments the model passed.
output	string	Tool output text; empty when the call failed.
error	any	The failure string when the call failed (also returned to the model in-band); null on success, matching OpenAI's mcp_call.
approval_request_id	any	The `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*	enum		mcp_list_tools
id*	string
server_label*	string
connector_id	string	Present only when the item originated from a managed connector.
tools*	McpToolDef[]
error	string	Present only when the server's tools could not be listed. Absent on success.

McpToolDefobject

One tool discovered on a remote MCP server.

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

MessageOutputItemobject

content*	ContentPart[]
id*	string
role*	enum	Role in a message	assistant
status*	enum	Status of a response or output item	completed \| failed \| incomplete \| in_progress \| queued \| cancelled
type*	enum		message

NamespaceToolobject

A response-only namespace containing complete external tool definitions.

type*	enum	namespace
name*	string
description*	string
tools*	NamespaceToolDef[]

NamespaceToolDefobject

One function definition discovered by hosted external-tool search.

type*	enum		function
name*	string
description	string
parameters	object	The server's JSON Schema for the tool, passed through unmodified.

OutputItemMessageOutputItem | SearchResultsOutputItem | ImageSearchResultsOutputItem | …

OutputTokensDetailsobject

reasoning_tokens*

integer

format: 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.

queries	string[]	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*	enum		people_search_results

ResponsesCostobject

Cost breakdown for a Responses API request

cache_creation_cost	number	Cost for cache creation in USD	format: double
cache_read_cost	number	Cost for cache reads in USD	format: double
currency*	enum	Currency of the cost values	USD
input_cost*	number	Cost for input tokens in USD	format: double
output_cost*	number	Cost for output tokens in USD	format: double
tool_calls_cost	number	Cost for tool call invocations in USD	format: double
tool_calls_cost_details	object	USD cost attributed to each reported tool by tool name. Unpriced reported tools are included with a value of 0.
total_cost*	number	Total cost for the request in USD	format: double

ResponsesObjectTypeenum

Object type in API responses

response

ResponsesUsageobject

Token usage and cost information for a Responses API request

cost	ResponsesCost	Cost breakdown for the request
input_tokens*	integer	Number of input tokens used	format: int64
input_tokens_details	object
output_tokens*	integer	Number of output tokens generated	format: int64
tool_calls_details	object	Details about tool call invocations
total_tokens*	integer	Total tokens used (input + output)	format: int64

RoleTypeenum

Role in a message

assistant

SandboxResultsOutputItemobject

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

type*	enum		sandbox_results
code	string	The code that was executed inside the sandbox.
stdout	string	Standard output captured from the sandbox execution.
stderr	string	Standard error captured from the sandbox execution.
exit_code	integer	Process exit code. Non-zero indicates a runtime error.	format: int32
duration_ms	integer	Wall-clock duration of the sandbox execution, in milliseconds.	format: int64
status*	enum	Execution status. One of `completed`, `timed_out`, `failed`.	completed \| timed_out \| failed

SearchResultobject

A single search result used in LLM responses

date	string	Publication date of the result
id*	integer	Unique numeric identifier for the result	format: int64
last_updated	string	Date the result was last updated
snippet*	string	Text snippet from the search result
source	enum	Source type of the result	web
title*	string	Title of the search result page
url*	string	URL of the search result page

SearchResultsOutputItemobject

queries	string[]
results*	SearchResult[]
type*	enum	search_results

SearchSourceenum

Source of search results

web

Statusenum

Status of a response or output item

ToolCallDetailsobject

Details about a tool call invocation

invocation	integer	Number of times this tool was invoked	format: int64
cost_usd	number	Accumulated customer charge in USD for this tool when the API can attribute one directly.	format: double
token_usage	ToolCallTokenUsage[]	Model token usage for tools backed by internal LLM calls. Sandbox SDK usage is aggregated by model.

ToolCallTokenUsageobject

model	string	Model identifier reported by the internal LLM call.
input_tokens*	integer	Total input tokens, including uncached, cache write, and cache read tokens.	format: int64
output_tokens*	integer	Output 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*	enum		tool_search_output
id*	string
call_id*	any	Always null for hosted search.
execution*	string	Execution location. Currently `server`. Clients must tolerate unknown values.
arguments	string	Exact argument text authored by the model for hosted search.
tools*	NamespaceTool[]
status*	string	Current execution status. Known values are `in_progress`, `completed`, and `incomplete`. Clients must tolerate unknown values.

UrlContentobject

Content fetched from a URL

snippet*	string	The fetched content snippet
title*	string	The title of the page
url*	string	The 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", …}]}