Retrieve Agent Response

GET/v1/agent/{id}Retrieve Agent Response

Retrieve a response created earlier. Returns a JSON snapshot of the response. Only responses created with store omitted or true can be retrieved; store: false responses return a 404.

Parameters

idstringpathrequired

Response id (`resp_<...>`)

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)

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

idrequiredpath parameter

curl -X GET 'https://api.perplexity.ai/v1/agent/string'

const response = await fetch('https://api.perplexity.ai/v1/agent/string', { method: 'GET' });
const data = await response.json();

const response = await fetch('https://api.perplexity.ai/v1/agent/string', { method: 'GET' });
console.log(await response.json());

import requests

response = requests.request("GET", "https://api.perplexity.ai/v1/agent/string")
print(response.json())

package main

import (
	"context"
	"net/http"
)

func main() {
	ctx := context.Background()
	req, err := http.NewRequestWithContext(ctx, "GET", "https://api.perplexity.ai/v1/agent/string", nil)
	if err != nil {
		panic(err)
	}
	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/string");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "GET");
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.perplexity.ai/v1/agent/string"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.perplexity.ai/v1/agent/string")
request = Net::HTTPGenericRequest.new("GET", false, true, uri)
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.Get, "https://api.perplexity.ai/v1/agent/string");
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

Retrieve Agent Response

Parameters

Responses

Skills

Operations