Output Control

Streaming Responses

Streaming allows you to receive partial responses from the Perplexity API as they are generated, rather than waiting for the complete response. This is particularly useful for real-time user experiences, long responses, and interactive applications.

Streaming is supported across all models available through the Agent API.

To enable streaming, set stream=True (Python) or stream: true (TypeScript) when creating responses:

from perplexity import Perplexity

client = Perplexity()

# Create streaming response
stream = client.responses.create(
    effort="fast",
    input="Explain what a model card is in the context of large language models: the typical sections (intended use, training data, limitations, evaluation).",
    stream=True
)

# Process streaming response
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="")
    elif event.type == "response.completed":
        print(f"\n\nCompleted: {event.response.usage}")

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

// Create streaming response
const stream = await client.responses.create({
  effort: "fast",
  input: "Explain what a model card is in the context of large language models: the typical sections (intended use, training data, limitations, evaluation).",
  stream: true
});

// Process streaming response
for await (const chunk of stream) {
  if (chunk.type === "response.output_text.delta") {
    process.stdout.write((chunk as any).delta);
  }
}

curl -X POST "https://api.perplexity.ai/v1/agent" \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "effort": "fast",
    "input": "Explain what a model card is in the context of large language models: the typical sections (intended use, training data, limitations, evaluation).",
    "stream": true
  }'

Response

{
  "id": "resp_081e7a0a-4087-403b-8e74-a997d28d6fd2",
  "created_at": 1779391825,
  "model": "openai/gpt-5.6-sol",
  "object": "response",
  "output": [
    {
      "results": [
        {
          "id": 1,
          "snippet": "Organizations developing and deploying AI, specifically generative AI, have turned to model cards as one way to promote explainability and achieve that transparency.\n...\nFirst proposed in 2018, model...",
          "title": "5 things to know about AI model cards | IAPP",
          "url": "https://iapp.org/news/a/5-things-to-know-about-ai-model-cards",
          "date": "2023-08-23",
          "last_updated": "2026-05-16",
          "source": "web"
        },
        {
          "id": 2,
          "snippet": "The term “Model Card” was coined by Mitchell et al. in the 2018 paper Model Cards for Model Reporting.\nAt their core, Model Cards are the nutrition labels of the AI world, providing instructions and...",
          "title": "Towards a Standard for Model Cards - Trustible",
          "url": "https://trustible.ai/post/towards-a-standard-for-model-cards/",
          "date": "2023-05-05",
          "last_updated": "2026-05-20",
          "source": "web"
        },
        {
          "id": 3,
          "snippet": "This work proposes model cards, a framework that can be used to document any trained machine learning model in the application fields of computer vision and natural language processing, and provides...",
          "title": "[PDF] Model Cards for Model Reporting - Semantic Scholar",
          "url": "https://www.semanticscholar.org/paper/Model-Cards-for-Model-Reporting-Mitchell-Wu/7365f887c938ca21a6adbef08b5a520ebbd4638f",
          "date": null,
          "last_updated": "2024-07-27",
          "source": "web"
        },
        {
          "id": 4,
          "snippet": "A model card is a type of documentation that is created for, and provided with, machine learning models.\nA model card functions as a type of data sheet, similar in principle to the consumer safety...",
          "title": "What is a model card in machine learning and what is its purpose?",
          "url": "https://www.techtarget.com/whatis/definition/model-card-in-machine-learning",
          "date": "2024-03-25",
          "last_updated": "2026-05-18",
          "source": "web"
        },
        {
          "id": 5,
          "snippet": "Model Cards are a powerful tool that promotes transparency, accountability, and regulatory compliance in Machine Learning & AI development.\n...\n{ts:43} data scientists so let's start with the basics...",
          "title": "Model Cards for Model Reporting - YouTube",
          "url": "https://www.youtube.com/watch?v=saAUB_MG2d0",
          "date": "2024-02-13",
          "last_updated": "2025-11-18",
          "source": "web"
        },
        {
          "id": 6,
          "snippet": "#### Simple, structured overviews of how an advanced AI model was designed and evaluated.",
          "title": "Model cards - Google DeepMind",
          "url": "https://deepmind.google/models/model-cards/",
          "date": null,
          "last_updated": "2026-05-20",
          "source": "web"
        },
        {
          "id": 7,
          "snippet": "The original framework specified: model details, intended use, factors (relevant demographic or contextual factors), metrics, evaluation data, training data, quantitative analyses, ethical...",
          "title": "The Model Card Nobody Reads — Bluewaves Boutique",
          "url": "https://bluewaves.boutique/notes/the-model-card-nobody-reads/",
          "date": "2025-12-23",
          "last_updated": "2026-04-08",
          "source": "web"
        },
        {
          "id": 8,
          "snippet": "This is the paper that started it all.\nMargaret Mitchell and her team at Google Research introduced model cards as a practical solution to the black box problem in machine learning.\nDrawing...",
          "title": "Model Cards for Model Reporting | KI-Governance-Bibliothek",
          "url": "https://verifywise.ai/de/ai-governance-library/transparency-and-documentation/model-cards-paper",
          "date": "2019-01-01",
          "last_updated": "2026-04-01",
          "source": "web"
        },
        {
          "id": 9,
          "snippet": "In this paper, we propose a framework that\nwe call model cards, to encourage such transparent model reporting.\nModel cards are short documents accompanying trained machine\nlearning models that...",
          "title": "[PDF] Model Cards for Model Reporting - arXiv",
          "url": "https://arxiv.org/pdf/1810.03993",
          "date": null,
          "last_updated": "2026-05-19",
          "source": "web"
        },
        {
          "id": 10,
          "snippet": "Model cards provides a standardized structure for conveying key information about AI models.\nGrounded in academic literature [7] and official guidelines from Hugging Face [17], model cards...",
          "title": "What's documented in AI? Systematic Analysis of 32K AI Model Cards",
          "url": "https://arxiv.org/html/2402.05160v1",
          "date": "2020-08-27",
          "last_updated": "2026-02-18",
          "source": "web"
        },
        {
          "id": 11,
          "snippet": "In this paper, we propose a framework that Fairness, Accountability, and Transparency, January 29–31, 2019, Atlanta, GA, we call model cards, to encourage such transparent model reporting.\n…\nModel...",
          "title": "Model Cards For Model Reporting | PDF | Machine Learning - Scribd",
          "url": "https://www.scribd.com/document/588702829/1810-03993",
          "date": "2025-09-06",
          "last_updated": "2026-01-19",
          "source": "web"
        }
      ],
      "type": "search_results",
      "queries": [
        "model card definition machine learning",
        "model card intended use limitations evaluation",
        "Mitchell model cards paper 2019"
      ]
    },
    {
      "id": "msg_41254287-8054-4973-a3a4-7e5fb617eea4",
      "content": [
        {
          "text": "A model card is a short, structured document that accompanies a trained machine‑learning or large language model and explains how it was built, how it performs, where it should and should not be used, and known risks or limitations.[web:4][web:9][web:10] It plays a similar role to a product spec sheet or nutrition label, but for AI systems.[web:2][web:4]\n\n## What a model card is\n\n- A **model** card is documentation shipped with an AI model that summarizes key technical, ethical, and practical details in a human-readable way.[web:4][web:9]  \n- It is meant for both technical and non‑technical stakeholders, so they can understand intended use cases, behavior, and trade‑offs of the model before deployment.[web:2][web:4][web:8]\n\n## Typical sections: high level\n\nMany templates exist, but most modern model cards for LLMs include recurring sections.[web:7][web:9][web:10]\n\n- Model details (name, version, developer, architecture, date, license).[web:7][web:9]  \n- Uses/intended use and out‑of‑scope uses.[web:4][web:9][web:10]  \n- Training and data sources.[web:9][web:10]  \n- Evaluation setup and metrics.[web:1][web:9][web:10]  \n- Limitations, biases, and ethical considerations.[web:2][web:7][web:9]  \n- Caveats, recommendations, and how to get started (API, examples).[web:7][web:9][web:10]\n\nFor your question, the four core sections are usually: intended use, training data, limitations, and evaluation.[web:9][web:10]\n\n## Intended use section\n\nThis section defines where the model is appropriate and where it is not.[web:2][web:4][web:9]\n\nTypical contents:\n\n- **Intended users and domains**: For example, “researchers and engineers building conversational assistants” or “classification of English news text.”[web:4][web:9]  \n- Supported use cases: Tasks like code generation, summarization, or translation that the model is designed and tested for.[web:1][web:6][web:10]  \n- Out‑of‑scope use: Explicit warnings against high‑risk contexts such as medical diagnosis, legal advice, biometric identification, or automated decision‑making without human review.[web:4][web:7][web:9]\n\nFor large language models, this section helps prevent over‑reliance on the model in safety‑critical or highly regulated settings.[web:1][web:4]\n\n## Training data section\n\nThis section describes what data the model learned from, usually at an aggregate level rather than listing every dataset.[web:9][web:10]\n\nTypical contents:\n\n- **Data sources and types**: High‑level description of web text, code repositories, books, forums, or proprietary corpora used.[web:9][web:10]  \n- Temporal and language coverage: Time span of data collection, languages included, and major domains (e.g., news vs. social media).[web:9][web:10]  \n- Preprocessing and filtering: How data was cleaned, deduplicated, or filtered for safety, hate speech, or personal information.[web:9][web:10]  \n- Known gaps or biases in data: For example, over‑representation of English or certain regions, and under‑representation of minority languages or dialects.[web:8][web:9]\n\nFor LLMs, training data descriptions are crucial to interpret why a model is strong in some languages or topics and weak in others.[web:8][web:10]\n\n## Limitations section\n\nThis section explicitly states what the model cannot reliably do and known failure modes.[web:2][web:7][web:9]\n\nTypical contents:\n\n- **Capability limits**: Issues like hallucinations (fabricated facts), poor reasoning on long chains, weak performance on low‑resource languages, or lack of up‑to‑date knowledge beyond a cutoff date.[web:7][web:9][web:10]  \n- Safety and bias concerns: Propensity to reproduce harmful stereotypes, toxic or unsafe content, or unfair performance across demographic groups.[web:1][web:8][web:9]  \n- Operational limits: Maximum context length, latency considerations, and scenarios where performance degrades (noisy input, adversarial prompts).[web:6][web:10]  \n- Dependency on user behavior: Notes that the model is sensitive to prompt phrasing and may be misused through prompt engineering.[web:7][web:9]\n\nThis section usually pairs limitations with recommendations such as human review, domain‑specific fine‑tuning, or additional guardrails.[web:7][web:9]\n\n## Evaluation section\n\nThe evaluation section documents how performance was measured and what the results were.[web:1][web:9][web:10]\n\nTypical contents:\n\n- **Benchmarks and tasks**: Lists of datasets or benchmark suites, such as question‑answering, reasoning, coding, or toxicity detection tests for LLMs.[web:1][web:9][web:10]  \n- Metrics: Accuracy, F1, BLEU, perplexity, safety scores, robustness metrics, or human evaluation ratings, chosen to reflect real‑world impact.[web:1][web:9][web:10]  \n- Conditions and subgroups: Performance broken down by language, topic domain, demographic attributes, or other relevant factors to reveal disparities.[web:1][web:8][web:9]  \n- Evaluation procedure: How data was split, decision thresholds, and any notable experimental assumptions.[web:9][web:11]\n\nFor large language models, this section often includes both capability benchmarks (e.g., reasoning and coding tests) and safety evaluations (e.g., red‑teaming or harmful content benchmarks).[web:1][web:6][web:10]",
          "type": "output_text",
          "annotations": [],
          "logprobs": []
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "status": "completed",
  "error": null,
  "usage": {
    "input_tokens": 6852,
    "output_tokens": 1316,
    "total_tokens": 8168,
    "cost": {
      "currency": "USD",
      "input_cost": 0.01307,
      "output_cost": 0.02632,
      "total_cost": 0.04332,
      "cache_creation_cost": null,
      "cache_read_cost": 0.00143,
      "tool_calls_cost": 0.0025
    },
    "input_tokens_details": {
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 3584,
      "cached_tokens": 3584
    },
    "tool_calls_details": {
      "search_web": {
        "invocation": 1
      }
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "completed_at": 1779391825
}

Error Handling

Handle errors gracefully during streaming:

import perplexity
from perplexity import Perplexity

client = Perplexity()

try:
    stream = client.responses.create(
        effort="fast",
        input="What is the FOMC, how often does it meet, and what tools (federal funds rate, balance sheet) does it use to influence the economy?",
        stream=True
    )
    
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="")
        elif event.type == "response.completed":
            print(f"\n\nCompleted: {event.response.usage}")
            
except perplexity.APIConnectionError as e:
    print(f"Network connection failed: {e}")
except perplexity.RateLimitError as e:
    print(f"Rate limit exceeded, please retry later: {e}")
except perplexity.APIStatusError as e:
    print(f"API error {e.status_code}: {e.response}")

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

try {
  const stream = await client.responses.create({
    effort: "fast",
    input: "What is the FOMC, how often does it meet, and what tools (federal funds rate, balance sheet) does it use to influence the economy?",
    stream: true
  });

  for await (const chunk of stream) {
    if (chunk.type === "response.output_text.delta") {
      process.stdout.write((chunk as any).delta);
    }
  }
} catch (error) {
  if (error instanceof Perplexity.APIConnectionError) {
    console.error("Network connection failed:", (error as any).cause);
  } else if (error instanceof Perplexity.RateLimitError) {
    console.error("Rate limit exceeded, please retry later");
  } else if (error instanceof Perplexity.APIError) {
    console.error(`API error ${error.status}: ${error.message}`);
  }
}

Response

{
  "id": "resp_bc5efb99-19ca-4185-87fa-890f2276edd7",
  "created_at": 1779391925,
  "model": "openai/gpt-5.6-sol",
  "object": "response",
  "output": [
    {
      "results": [
        {
          "id": 1,
          "snippet": "The Federal Reserve controls the three tools of monetary policy--open market operations, the discount rate, and reserve requirements.\nThe Board of Governors of the Federal Reserve System is...",
          "title": "The Fed - Federal Open Market Committee",
          "url": "https://www.federalreserve.gov/monetarypolicy/fomc.htm",
          "date": "2026-04-29",
          "last_updated": "2026-05-12",
          "source": "web"
        },
        {
          "id": 2,
          "snippet": "What does “FOMC” stand for?\nThe Federal Open Market Committee, or FOMC, is the Fed’s chief body for monetary policy.\nIts voting membership combines the seven members of the Board of Governors, the...",
          "title": "Introduction to the FOMC (Federal Open Market Committee)",
          "url": "https://www.stlouisfed.org/in-plain-english/introduction-to-the-fomc",
          "date": null,
          "last_updated": "2026-05-12",
          "source": "web"
        },
        {
          "id": 3,
          "snippet": "The Federal Open Market Committee (FOMC) is the monetary policymaking body of the Federal Reserve System.\nThe FOMC is composed of 12 members--the seven members of the Board of Governors and five of...",
          "title": "What is the FOMC and when does it meet? - Federal Reserve",
          "url": "https://www.federalreserve.gov/faqs/about_12844.htm",
          "date": "2019-01-30",
          "last_updated": "2026-03-30",
          "source": "web"
        },
        {
          "id": 4,
          "snippet": "The **Federal Open Market Committee** (**FOMC**) is a committee within the Federal Reserve System (colloquially \"the Fed\") that is charged under United States law with overseeing the nation's open...",
          "title": "Federal Open Market Committee - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/Federal_Open_Market_Committee",
          "date": "2004-04-13",
          "last_updated": "2026-03-31",
          "source": "web"
        },
        {
          "id": 5,
          "snippet": "\"The committee meets eight times a year, or about once every six weeks,\" writes Kiplinger contributor Dan Burrows in his feature, \"When Is the Next Fed Meeting?\".\nThe Federal Open Market Committee...",
          "title": "April Fed Meeting: Live Updates and Commentary | Kiplinger",
          "url": "https://www.kiplinger.com/news/live/fed-meeting-updates-and-commentary-april-2026",
          "date": "2026-04-29",
          "last_updated": "2026-05-21",
          "source": "web"
        },
        {
          "id": 6,
          "snippet": "The Fed’s dual mandate requires it to ensure both stable prices and maximum employment.",
          "title": "Tracker: The Federal Reserve's Balance Sheet Assets - AAF",
          "url": "https://www.americanactionforum.org/insight/tracker-the-federal-reserves-balance-sheet/",
          "date": "2026-05-14",
          "last_updated": "2026-05-16",
          "source": "web"
        },
        {
          "id": 7,
          "snippet": "The Federal Open Market Committee (FOMC) meeting is a regular session held by the members of the Federal Open Market Committee, a branch of the Federal Reserve that decides on the monetary policy of...",
          "title": "When is the FOMC Meeting and Announcement? - IG",
          "url": "https://www.ig.com/en-ch/financial-events/fomc-meeting-announcement",
          "date": "2019-06-28",
          "last_updated": "2026-05-21",
          "source": "web"
        },
        {
          "id": 8,
          "snippet": "The Federal Reserve (Fed) influences borrowing costs, savings returns, and overall financial conditions across the economy.\n...\n### Why does the Federal Reserve raise or lower interest rates?\naThe...",
          "title": "Federal Reserve Monetary Policy | U.S. Bank",
          "url": "https://www.usbank.com/investing/financial-perspectives/market-news/federal-reserve-tapering-asset-purchases.html",
          "date": "2026-05-01",
          "last_updated": "2026-05-11",
          "source": "web"
        }
      ],
      "type": "search_results",
      "queries": [
        "FOMC purpose and structure",
        "FOMC meeting schedule eight times a year",
        "FOMC policy tools federal funds rate balance sheet"
      ]
    },
    {
      "id": "msg_6e56cea0-aee5-4b0c-a952-31a48542f67f",
      "content": [
        {
          "text": "The Federal Open Market Committee (FOMC) is the Federal Reserve’s main monetary policymaking body, and it typically meets eight times per year—about once every six weeks, with extra meetings if needed.[web:1][web:2][web:3] It influences the economy primarily by setting the target range for the federal funds rate and by adjusting the size and composition of the Federal Reserve’s balance sheet through open market operations and asset purchases or sales.[web:1][web:3][web:4]  \n\n## What the FOMC is  \n\n- The FOMC is the **monetary** policymaking arm of the Federal Reserve System, responsible for decisions that guide U.S. interest rates and money supply.[web:3][web:4]  \n- It oversees open market operations, including the buying and selling of U.S. Treasury and agency securities, which are central to how monetary policy is implemented.[web:1][web:4]  \n\n## How often it meets  \n\n- The FOMC schedules eight regular meetings each year, roughly one every six weeks, and is legally required to meet at least four times annually.[web:1][web:3][web:4]  \n- It can hold additional unscheduled meetings when economic or financial conditions warrant a faster policy response.[web:2][web:3]  \n\n## Federal funds rate tool  \n\n- The committee sets a target level or range for the federal funds rate, the overnight interest rate at which banks lend reserves to each other.[web:3][web:4][web:8]  \n- By raising this target range, the FOMC tightens financial conditions to cool inflation and economic activity; by lowering it, the FOMC aims to stimulate borrowing, spending, and employment.[web:3][web:8]  \n\n## Balance sheet and open market operations  \n\n- Through open market operations, the FOMC directs the purchase or sale of Treasury and agency securities, which changes the amount of reserves in the banking system and affects interest rates.[web:1][web:4]  \n- Since 2008, the FOMC has also used large‑scale asset purchases (expanding the Fed’s **balance** sheet) or allowing assets to run off/shrink to influence longer‑term interest rates and broader financial conditions.[web:3][web:6]  \n\n## Other policy tools in the background  \n\n- In addition to the federal funds rate and balance sheet policies, the broader Federal Reserve toolkit includes the discount rate and reserve requirements, though open market operations are specifically under the FOMC’s direction.[web:1]  \n- Together, these tools are used to pursue the Fed’s dual mandate of maximum employment and stable prices in the U.S. economy.[web:3][web:6]",
          "type": "output_text",
          "annotations": [],
          "logprobs": []
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "status": "completed",
  "error": null,
  "usage": {
    "input_tokens": 6315,
    "output_tokens": 631,
    "total_tokens": 6946,
    "cost": {
      "currency": "USD",
      "input_cost": 0.01092,
      "output_cost": 0.01262,
      "total_cost": 0.02747,
      "cache_creation_cost": null,
      "cache_read_cost": 0.00143,
      "tool_calls_cost": 0.0025
    },
    "input_tokens_details": {
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 3584,
      "cached_tokens": 3584
    },
    "tool_calls_details": {
      "search_web": {
        "invocation": 1
      }
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "completed_at": 1779391925
}

If you need search results immediately for your user interface, consider using non-streaming requests for use cases where search result display is critical to the real-time user experience.

Background Runs

Streaming keeps a connection open for the lifetime of the run. For runs that take minutes — deep research, heavy sandbox work — submit with background: true instead, then poll for the result by ID. The run continues server-side even if your client disconnects.

For the full background-run lifecycle — submitting, polling on terminal status, streaming with reconnect, and cancelling — see Background mode.

import time
from perplexity import Perplexity

client = Perplexity()


def get_output_text(response) -> str:
    return "".join(
        content.text
        for item in response.output or []
        if getattr(item, "type", None) == "message"
        for content in getattr(item, "content", None) or []
        if getattr(content, "type", None) == "output_text"
    )


response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Produce a competitive landscape report for the EV charging market.",
    tools=[{"type": "web_search"}, {"type": "sandbox"}],
    max_steps=10,
    background=True,
)

while response.status in ("queued", "in_progress"):
    time.sleep(2)
    response = client.responses.retrieve(response.id)

print(get_output_text(response))

# 1. Submit in the background
curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Produce a competitive landscape report for the EV charging market.",
    "tools": [{ "type": "web_search" }, { "type": "sandbox" }],
    "max_steps": 10,
    "background": true
  }'

# 2. Poll by id until status is completed, failed, cancelled, or incomplete
curl https://api.perplexity.ai/v1/agent/$RESPONSE_ID \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY"

Background runs are durable, so you can also stream one live and reconnect after a drop. Request GET /v1/agent/{id}?stream=true&starting_after=N to resume from the event after sequence number N. Reconnect is only valid within the response’s reconnect window; once that window expires, the endpoint returns 400, and you fall back to a plain GET /v1/agent/{id} for the final snapshot. See the Agent API reference.

Structured Outputs

Structured outputs enable you to enforce specific response formats from Perplexity’s models, ensuring consistent, machine-readable data that can be directly integrated into your applications without manual parsing. We currently support JSON Schema structured outputs. To enable structured outputs, add a response_format field to your request:

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "your_schema_name",
      "schema": { /* your JSON schema object */ }
    }
  }
}

The name field is required and must be 1-64 alphanumeric characters. The schema should be a valid JSON schema object. LLM responses will match the specified format unless the output exceeds max_tokens. Properties listed in the schema’s required array are required in the output. Every declared property omitted from required remains optional and may resolve to JSON null. If required is omitted or empty, all declared properties are optional. This behavior is the same for streaming and non-streaming requests on both /v1/agent and its /v1/responses compatibility alias.

Improve Schema Compliance: Give the LLM some hints about the output format in your prompts to improve adherence to the structured format. For example, include phrases like “Please return the data as a JSON object with the following structure…” or “Extract the information and format it as specified in the schema.”

The first request with a new JSON Schema expects to incur delay on the first token. Typically, it takes 10 to 30 seconds to prepare the new schema, and may result in timeout errors. Once the schema has been prepared, the subsequent requests will not see such delay.

Example

from perplexity import Perplexity
from typing import List, Optional
from pydantic import BaseModel

class FinancialMetrics(BaseModel):
    company: str
    quarter: str
    revenue: float
    net_income: float
    eps: float
    revenue_growth_yoy: Optional[float] = None
    key_highlights: List[str]

client = Perplexity()

response = client.responses.create(
    effort="low",
    input="Explain the structure of an SEC Form 10-K filing: what each major item (Item 1 Business, Item 1A Risk Factors, Item 7 MD&A, Item 8 Financial Statements) typically contains.",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "financial_metrics",
            "schema": {
                **FinancialMetrics.model_json_schema(),
                "additionalProperties": False,
            }
        }
    }
)

metrics = FinancialMetrics.model_validate_json(response.output_text)
print(f"Revenue: ${metrics.revenue}B")

import Perplexity from '@perplexity-ai/perplexity_ai';

interface FinancialMetrics {
  company: string;
  quarter: string;
  revenue: number;
  net_income: number;
  eps: number;
  revenue_growth_yoy?: number;
  key_highlights: string[];
}

const client = new Perplexity();

const response = await client.responses.create({
  effort: 'low',
  input: 'Explain the structure of an SEC Form 10-K filing: what each major item (Item 1 Business, Item 1A Risk Factors, Item 7 MD&A, Item 8 Financial Statements) typically contains.',
  response_format: {
    type: 'json_schema',
    json_schema: {
      name: 'financial_metrics',
      schema: {
        type: 'object',
        properties: {
          company: { type: 'string' },
          quarter: { type: 'string' },
          revenue: { type: 'number' },
          net_income: { type: 'number' },
          eps: { type: 'number' },
          revenue_growth_yoy: { anyOf: [{ type: 'number' }, { type: 'null' }] },
          key_highlights: { anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'null' }] }
        },
        required: ['company', 'quarter', 'revenue', 'net_income', 'eps', 'key_highlights'],
        additionalProperties: false
      }
    }
  }
});

const metrics: FinancialMetrics = JSON.parse(response.output_text ?? '{}');

curl -X POST "https://api.perplexity.ai/v1/agent" \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "effort": "low",
    "input": "Explain the structure of an SEC Form 10-K filing: what each major item (Item 1 Business, Item 1A Risk Factors, Item 7 MD&A, Item 8 Financial Statements) typically contains.",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "financial_metrics",
        "schema": {
          "type": "object",
          "properties": {
            "company": {"type": "string"},
            "quarter": {"type": "string"},
            "revenue": {"type": "number"},
            "net_income": {"type": "number"},
            "eps": {"type": "number"},
            "revenue_growth_yoy": {"type": "number"},
            "key_highlights": {
              "type": "array",
              "items": {"type": "string"}
            }
          },
          "required": ["company", "quarter", "revenue", "net_income", "eps", "key_highlights"]
        }
      }
    }
  }' | jq

Response

{
  "id": "resp_04a4e751-4810-40c2-a92e-ffcab3e11d77",
  "created_at": 1779391825,
  "model": "openai/gpt-5.6-sol",
  "object": "response",
  "output": [
    {
      "results": [
        {
          "id": 1,
          "snippet": "(d) In response to Item l, Business, such registrant only need furnish a brief\ndescription of the business done by the registrant and its subsidiaries during the\nmost recent fiscal year which will...",
          "title": "[PDF] Form 10-K - SEC.gov",
          "url": "https://www.sec.gov/files/form10-k.pdf",
          "date": null,
          "last_updated": "2025-06-03",
          "source": "web"
        },
        {
          "id": 2,
          "snippet": "This report provides a comprehensive view of a company’s financial position and additional business disclosures, such as key operational details, audited financial statements, market risks, and...",
          "title": "How to navigate Forms 10-K, 10-Q, 20-F, 40-F, 8-K and 6-K",
          "url": "https://www.toppanmerrill.com/blog/how-to-navigate-forms-10-k-10-q-20-f-40-f-8-k-and-6-k/",
          "date": "2025-03-19",
          "last_updated": "2026-05-16",
          "source": "web"
        },
        {
          "id": 3,
          "snippet": "The SEC breaks the Form 10-K down into four parts:\n### Part I\n- Item 1: “Business”\n- Item 1A: “Risk Factors”\n- Item 1B: “Unresolved Staff Comments”\n- Item 2: “Properties”\n...\nTo analyze a company...",
          "title": "What Form 10-K Is and How to Understand It to Use It",
          "url": "https://thecollegeinvestor.com/32956/form-10-k/",
          "date": "2024-02-27",
          "last_updated": "2025-04-18",
          "source": "web"
        },
        {
          "id": 4,
          "snippet": "#### Item 1 – Business\nThis describes the business of the company: who and what the company does, what subsidiaries it owns, and what markets it operates in.\nIt may also include recent events...",
          "title": "Form 10-K - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/Form_10-K",
          "date": "2005-02-23",
          "last_updated": "2026-03-31",
          "source": "web"
        },
        {
          "id": 5,
          "snippet": "Regulation S-K, Item 105, requires registrants to provide “a discussion of the\nmaterial factors that make an investment in the registrant or offering\nspeculative or risky.”\nCertain indicators of risk...",
          "title": "3.3 Disclosures About Risk | DART – Deloitte Accounting Research ...",
          "url": "https://dart.deloitte.com/USDART/home/publications/deloitte/additional-deloitte-guidance/roadmap-sec-comment-letter-considerations/chapter-3-sec-disclosure-topics/3-3-disclosures-about-risk",
          "date": null,
          "last_updated": "2026-03-31",
          "source": "web"
        },
        {
          "id": 6,
          "snippet": "If the registrant or any of its subsidiaries consolidated has completed the acquisition or \ndisposition of a significant amount of assets, otherwise than in the ordinary course of business, or \nthe...",
          "title": "[PDF] Form 8-K - SEC.gov",
          "url": "https://www.sec.gov/files/form8-k.pdf",
          "date": null,
          "last_updated": "2025-04-11",
          "source": "web"
        },
        {
          "id": 7,
          "snippet": "#### Part I: Business Overview and Risks\n- Item 1 - Business:\n- Describes the company’s primary business activities, including its main products and services, subsidiaries, and market operations.\n-...",
          "title": "Form 10-K: Explained",
          "url": "https://unlevered.ai/blog/10-k/",
          "date": "2024-08-21",
          "last_updated": "2024-10-17",
          "source": "web"
        },
        {
          "id": 8,
          "snippet": "- **Item 1: Business**\n...\n## Item 1 - BusinessneCompanies typically define their business in this opening section of the 10-K report.\nThey describe their various product lines and business segments...",
          "title": "The 10-K - SEC Filings - Research Guides at Baruch College",
          "url": "https://guides.newman.baruch.cuny.edu/c.php?g=188202&p=1244183",
          "date": "2009-11-02",
          "last_updated": "2026-05-09",
          "source": "web"
        },
        {
          "id": 9,
          "snippet": "- **Item 1A: Risk Factors:** Absolutely critical reading.\nThis **section** lists the most significant risks and uncertainties that could materially affect the company’s business, **financial...",
          "title": "How to Read a 10-K Report with AI | Complete SEC Analysis Guide",
          "url": "https://www.v7labs.com/blog/how-to-read-a-10k-report-ai-sec-filings-guide",
          "date": "2025-06-11",
          "last_updated": "2026-05-16",
          "source": "web"
        },
        {
          "id": 10,
          "snippet": "Additional sections in this Form 10-K which should be helpful to the reading of our discussion and analysis include the following: (i) a description of our services provided, by segment found in...",
          "title": "Form 10-K Item 7. Management's Discussion and Analysis",
          "url": "https://www.sec.gov/Archives/edgar/data/1449732/000119312512289206/d374099dex993.htm",
          "date": "2012-03-29",
          "last_updated": "2025-09-23",
          "source": "web"
        },
        {
          "id": 11,
          "snippet": "In this section of the 10-K, companies will provide a description of the business, including what the company does, its different business lines and customers, competitors, and where it operates...",
          "title": "Form 10-K: A Comprehensive Overview - Corporate Finance Institute",
          "url": "https://corporatefinanceinstitute.com/resources/accounting/form-10-k/",
          "date": "2024-04-18",
          "last_updated": "2026-02-04",
          "source": "web"
        },
        {
          "id": 12,
          "snippet": "Unlike the quarterly 10-Q, the 10-K includes\n**audited financial statements** and extensive narrative sections covering the business model, competitive landscape, and risk factors.\n...\n#### Item 1...",
          "title": "SEC Form 10-K: Complete Guide to Annual Reports",
          "url": "https://secwhisperer.com/learn/sec-form-10k",
          "date": "2025-10-28",
          "last_updated": "2025-12-23",
          "source": "web"
        }
      ],
      "type": "search_results",
      "queries": [
        "SEC Form 10-K item 1 business description",
        "SEC Form 10-K item 1A risk factors description",
        "SEC Form 10-K item 7 MD&A contents",
        "SEC Form 10-K item 8 financial statements contents",
        "SEC form 10-K item list overview"
      ]
    },
    {
      "id": "msg_e2eaeb8f-a3ef-47ac-b50a-e5da20409664",
      "content": [
        {
          "text": "An SEC Form 10-K is a standardized annual report with specific “Items” that each serve a distinct purpose; Items 1, 1A, 7, and 8 together explain what the company does, what could go wrong, how management interprets the numbers, and the audited financials themselves.[web:1][web:4] Understanding the typical contents of each of these items makes it much easier to navigate any company’s filing.[web:8]  \n\n## Item 1 – Business  \n\nItem 1 “Business” describes the **core** operations of the registrant and its subsidiaries, including what the company does, its main products and services, and the markets and geographies in which it operates.[web:1][web:4][web:11] It often includes discussion of business segments, major customers, distribution channels, and important contracts or supply arrangements.[web:8][web:11]  \n\nCompanies typically also cover their competitive environment, key competitors, and the basis of competition (price, technology, brand, service).[web:4][web:8] Depending on the industry, this section may address regulatory requirements, seasonality of the business, research and development, intellectual property, dependence on raw materials, and human capital resources such as employees and labor relations.[web:4][web:7][web:8]  \n\n## Item 1A – Risk Factors  \n\nItem 1A “Risk Factors” presents the material risks that could adversely affect the company’s business, financial condition, or results of operations, framed as factors that make an investment speculative or risky.[web:1][web:5][web:9] These risk factors must focus on risks that are specific and material to the registrant, not just generic boilerplate, and are required to be written in plain-English style.[web:1][web:5]  \n\nTypical categories include business and operational risks (e.g., supply chain disruption, competition), financial risks (liquidity, leverage, credit), legal and regulatory risks, cybersecurity and data privacy risks, and macroeconomic or geopolitical risks.[web:7][web:9] The section usually explains how each risk could impact the company (for example, reduced revenue, higher costs, or asset impairment) and may note interdependencies between risks.[web:7][web:9]  \n\n## Item 7 – MD&A  \n\nItem 7 “Management’s Discussion and Analysis of Financial Condition and Results of Operations” (MD&A) is where management explains, in narrative form, the drivers behind the historical financial results and the company’s liquidity and capital resources.[web:1][web:9][web:11] It typically walks through year‑over‑year changes in revenue, margins, expenses, and key line items, linking them to underlying causes such as volume, pricing, mix, acquisitions, foreign exchange, or cost initiatives.[web:9][web:10][web:11]  \n\nMD&A also addresses liquidity (cash flows, debt arrangements, credit facilities), capital expenditures, and known trends, demands, commitments, or uncertainties that are reasonably likely to affect future performance.[web:1][web:9] Companies often discuss non‑GAAP measures, critical accounting estimates, and sensitivity to market risks such as interest rates or foreign exchange, with cross‑references to the financial statements and risk factors.[web:9][web:10][web:11]  \n\n## Item 8 – Financial Statements  \n\nItem 8 contains the company’s audited annual financial statements and related disclosures.[web:1][web:2][web:12] This section typically includes the independent auditor’s report, the balance sheet, income statement, statement of cash flows, statement of shareholders’ equity, and the accompanying notes to the financial statements.[web:2][web:9][web:12]  \n\nThe notes provide detailed information on accounting policies, revenue recognition, segments, debt, leases, contingencies, income taxes, pensions, stock-based compensation, and other significant matters.[web:2][web:12] Item 8 may also include financial statement schedules and any additional required data that support or expand on the primary financial statements.[web:1][web:12]",
          "type": "output_text",
          "annotations": [],
          "logprobs": []
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "status": "completed",
  "error": null,
  "usage": {
    "input_tokens": 6393,
    "output_tokens": 944,
    "total_tokens": 7337,
    "cost": {
      "currency": "USD",
      "input_cost": 0.01124,
      "output_cost": 0.01888,
      "total_cost": 0.03405,
      "cache_creation_cost": null,
      "cache_read_cost": 0.00143,
      "tool_calls_cost": 0.0025
    },
    "input_tokens_details": {
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 3584,
      "cached_tokens": 3584
    },
    "tool_calls_details": {
      "search_web": {
        "invocation": 1
      }
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "completed_at": 1779391825
}

Links in JSON Responses: Requesting links as part of a JSON response may not always work reliably and can result in hallucinations or broken links. Models may generate invalid URLs when forced to include links directly in structured outputs.To ensure all links are valid, use the links returned in the citations or search_results fields from the API response. Never count on the model to return valid links directly as part of the JSON response content.

Getting Started

Orchestrator API

Agent API

Search API

Embeddings API

Decisions API

Perplexity SDK

Admin & Management

Resources

Streaming Responses

Error Handling

Background Runs

Structured Outputs

Example

Next Steps

Structure the output

Agent API Models

​Streaming Responses

​Error Handling

​Background Runs

​Structured Outputs

​Example

​Next Steps

Structure the output

Agent API Models

Streaming Responses

Error Handling

Background Runs

Structured Outputs

Example

Next Steps