Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Equity Research Brief

A command-line tool that generates a structured equity research brief for any public ticker using Perplexity’s Agent API and the built-in finance_search tool. finance_search returns structured market data — quotes, financials, earnings transcripts, peer comparisons, analyst estimates — so the model can compose a report grounded in numbers, not just narrative. The tool is purpose-built for agentic investor workflows.

​
Features

  • One command produces a 6-section brief: snapshot, business overview, financial trajectory, latest earnings, peer context, risks, bottom line
  • Uses the Agent API’s finance_search tool for structured fundamentals, quotes, and earnings-call transcripts
  • Three preset configurations matching the official finance_search recommendations:
    • quote — live price/quote only, fastest and cheapest
    • single — single-company historical lookup with web context
    • research — full multi-step cross-company brief (default)
  • Prints citation-ready Perplexity finance source URLs alongside the brief
  • Reports finance_search invocation count and total request cost
  • --json flag emits the raw Agent API response for downstream pipelines

​
Prerequisites

  • Python 3.9+
  • A Perplexity API key with Agent API access. finance_search is currently in beta — see the Finance Search docs for availability.

​
Installation

cd docs/examples/equity-research-brief
pip install -r requirements.txt
chmod +x equity_research_brief.py

​
API Key Setup

export PERPLEXITY_API_KEY="your-api-key-here"
You can also pass the key via --api-key, or place it in a .pplx_api_key file in the working directory.

​
Quick Start

Generate a full research brief on NVIDIA: 
./equity_research_brief.py NVDA

​
Usage

./equity_research_brief.py TICKER [--config {quote,single,research}] [--json] [--api-key KEY]

​
Just a live quote (cheapest, ~1 tool call)

./equity_research_brief.py AAPL --config quote

​
Single-company historical lookup with web context

./equity_research_brief.py MSFT --config single

​
Full multi-step research brief (default)

./equity_research_brief.py NVDA --config research

​
Emit raw Agent API JSON

./equity_research_brief.py TSLA --json | jq '.usage.cost'

​
Configuration Reference

ConfigModelToolsMax stepsBest for
quoteperplexity/sonarfinance_search1Live prices, quotes, fastest path
singleopenai/gpt-5.5web_search + finance_search + fetch_url5One-company historical fundamentals
researchanthropic/claude-opus-4-7web_search + finance_search + fetch_url10Multi-company comparisons, full brief
These configurations are taken directly from the finance_search recommended configurations.

​
Example Output (truncated)

## 1. Snapshot

- **Price:** $200.23 (as of 2026-05-01 14:10 UTC)
- **Market cap:** $4.87T
- **P/E (TTM):** 40.86
- **52-week range:** $110.82 – $216.83

## 2. Business overview

NVIDIA designs accelerated computing platforms — GPUs, networking, and full-stack
software — used in AI training and inference, gaming, professional visualization,
and automotive. Data Center is the dominant revenue line.

## 3. Financial trajectory
| FY    | Revenue     | Operating margin | Net income |
| ----- | ----------- | ---------------- | ---------- |
| FY25  | $130.5B     | 62.4%            | $72.9B     |
...

---
finance_search: 4 invocation(s) across categories [earnings_history, financials, profile, quote]

Finance sources:
  - https://www.perplexity.ai/finance/NVDA
  - https://www.perplexity.ai/finance/NVDA/earnings?eventId=409967
  - ...

Cost: 0.2817 USD

​
Code Walkthrough

The script does three things: 1. Issue a single Agent API call with finance_search enabled. 
from perplexity import Perplexity

client = Perplexity()
response = client.responses.create(
    model="anthropic/claude-opus-4-7",
    instructions=SYSTEM_PROMPT,
    input=BRIEF_TEMPLATE.format(ticker="NVDA"),
    tools=[
        {"type": "web_search"},
        {"type": "finance_search"},
        {"type": "fetch_url"},
    ],
    max_output_tokens=4096,
    max_steps=10,
)
The model decides which finance_search categories to fetch (quote, financials, transcript, etc.) based on the prompt. You don’t need to hand-pick fields. 2. Walk response.output to extract both the assistant text and the structured finance_results blocks. 
for item in response.output:
    if item.type == "finance_results":
        for r in item.results:
            print(r.category, r.tickers, r.sources)
    elif item.type == "message":
        for block in item.content:
            if block.type == "output_text":
                print(block.text)
3. Surface cost and finance source URLs alongside the prose. The Perplexity finance pages returned in result.sources are stable, citation-ready links — useful when the brief is consumed by humans or by a downstream RAG pipeline.

​
Prompting Guidance

finance_search works best when the prompt asks for a business outcome, not for specific data shapes. The system prompt instructs the model to:
  • be quantitative and attribute numbers to the right period (e.g. FY2025, Q3 FY26)
  • never invent numbers — if finance_search doesn’t return a field, say so explicitly
  • format the output in clean Markdown
This pattern is documented in the finance_search prompt guidance.

​
Pricing

finance_search is billed at $5 per 1,000 invocations, separate from model token usage. Each preset has different cost characteristics:
  • quote: typically 1 invocation, ~$0.007 per brief
  • single: 1–3 invocations + GPT-5.5 tokens
  • research: 3–6 invocations + Claude Opus tokens
See Perplexity Pricing for current rates.

​
Limitations

  • finance_search is currently in beta and may not be enabled on all API keys
  • Results depend on Perplexity’s finance data coverage; obscure or non-US tickers may return less structured data
  • This is not investment advice. The “Bottom line” section is explicitly framed as analytical opinion, not a recommendation

​
Resources