> ## 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.
# Finance Search
> Retrieve structured financial and market data in the Agent API.
## Overview
`finance_search` lets the model pull structured financial and market data for public companies, ETFs, and related instruments. The model decides which fields to fetch based on your prompt.
Use it when one answer needs more than one type of financial data, such as valuation, earnings, and context for the same company or list of companies.
### Capabilities
| Data area | What it includes |
| ------------------------------- | ------------------------------------------------------------------------------------------------- |
| Company basics | Quotes, profiles, peers, and market metadata |
| Financials | Income statement, balance sheet, cash flow (quarterly and annual), key ratios |
| Valuation and pricing | Current/near-real-time pricing, 1-minute to 1-month OHLCV ranges, pre-market and after-hours data |
| Earnings | Last earnings call transcript, report filings, beat/miss history, guidance discussion |
| Segment and KPI tracking | Revenue/profit by segment, geography, ARPU, subscriber counts, GMV, and other operating metrics |
| Analyst coverage | Forward revenue and EPS estimates, cover count, historical estimate changes |
| Market activity | Top gainers, top losers, and most active symbols |
| Ownership and corporate actions | Insider activity, ticker-level metadata, splits, and related market events |
| ETF and index details | Top constituents, shares, weights, and market values |
## Quickstart
Add `finance_search` to the `tools` array.
```python Python theme={null}
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="perplexity/sonar",
input="What's NVIDIA trading at right now, and what is its current P/E?",
tools=[{"type": "finance_search"}]
)
for item in response.output:
if item.type == "message":
print(item.content[0].text)
```
```bash cURL theme={null}
curl -X POST "https://api.perplexity.ai/v1/agent" \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "What is NVIDIA trading at right now, and what is its current P/E?",
"tools": [
{"type": "finance_search"}
]
}'
```
```json theme={null}
{
"background": false,
"completed_at": 1777644610,
"created_at": 1777644610,
"error": null,
"frequency_penalty": 0,
"id": "resp_d0476d0f-872d-492a-907e-1daa48eb9e32",
"incomplete_details": null,
"instructions": null,
"max_output_tokens": 8192,
"max_tool_calls": null,
"metadata": {},
"model": "perplexity/sonar",
"object": "response",
"output": [
{
"categories": ["quote"],
"results": [
{
"category": "quote",
"content": "## NVDA Quote\nQuote field guide: `price` is the latest quote/current price...\n| symbol | name | timestamp | market_status | price | currency | change | changesPercentage | marketCap | pe | eps | volume | dayLow | dayHigh | yearLow | yearHigh | previousClose | open |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| NVDA | NVIDIA Corporation | 2026-05-01 14:10:07 UTC | open | 200.23 | USD | 0.66 | 0.33 | 4,866,492,706,948 | 40.86 | 4.90 | 28,725,330 | 199.15 | 203 | 110.82 | 216.83 | 199.57 | 201.28 |",
"sources": [
"https://www.perplexity.ai/finance/NVDA/historical-data",
"https://www.perplexity.ai/finance/NVDA"
],
"tickers": ["NVDA"]
}
],
"tickers": ["NVDA"],
"type": "finance_results"
},
{
"content": [
{
"annotations": [],
"logprobs": [],
"text": "NVIDIA (NVDA) is currently trading at **$200.23** per share, and its current P/E ratio is **40.86**.",
"type": "output_text"
}
],
"id": "msg_b188058f-8225-4642-90e6-da7112f96b69",
"role": "assistant",
"status": "completed",
"type": "message"
}
],
"parallel_tool_calls": true,
"presence_penalty": 0,
"previous_response_id": null,
"prompt_cache_key": null,
"reasoning": null,
"safety_identifier": null,
"service_tier": "default",
"status": "completed",
"store": true,
"temperature": 1,
"text": {
"format": {
"type": "text"
}
},
"tool_choice": "auto",
"tools": [
{
"type": "finance_search"
}
],
"top_logprobs": 0,
"top_p": 1,
"truncation": "disabled",
"usage": {
"cost": {
"currency": "USD",
"input_cost": 0.00189,
"output_cost": 0.00016,
"tool_calls_cost": 0.005,
"total_cost": 0.00705
},
"input_tokens": 7570,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 63,
"output_tokens_details": {
"reasoning_tokens": 0
},
"tool_calls_details": {
"finance_search": {
"invocation": 1
}
},
"total_tokens": 7633
},
"user": null
}
```
## Example Prompts
* **Full company brief:** "Give me a complete NVIDIA snapshot: valuation, segment revenue for the latest quarter, and management's latest commentary on margins guidance."
* **Compare companies in one request:** "Compare Apple, Microsoft, and Alphabet on revenue growth, operating margin, and forward P/E for the latest fiscal year."
* **Earnings + reaction context:** "Summarize Tesla's last earnings call, include actual vs consensus, and describe how the stock and analyst targets moved after publication."
## Prompt Guidance
`finance_search` works best when the prompt states the outcome, not the data shape.
* Start with the business question first, then include the company or ticker.
* Add time windows when relevant (`latest quarter`, `fiscal year to date`, `last 30 days`).
* Let the tool decide which specific report fields to retrieve.
## Recommended Configurations
Start with the configuration that matches the shape of the finance question.
| Configuration | Best for | Latency | Quality | Cost |
| --------------------------------- | -------------------------------------------------------- | -------- | ------- | ------ |
| Live Market Data and Quotes | Real-time prices, quotes, and latest figures | Fast | Good | Low |
| Single-Company Historical Lookups | Basic historical financials for one company or ticker | Balanced | High | Medium |
| Multi-Step Financial Research | Cross-company comparisons and complex financial analysis | Thorough | Highest | High |
### Live Market Data and Quotes
Use this for time-sensitive answers that depend on real-time prices, quotes, or the latest market figures. It is the cheapest and fastest option while maintaining strong quality for live data lookups.
```python Python theme={null}
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="perplexity/sonar",
input="What is Apple trading at right now, and what is its latest market cap?",
tools=[{"type": "finance_search"}],
max_steps=1,
max_output_tokens=1024
)
for item in response.output:
if item.type == "message":
print(item.content[0].text)
```
```bash cURL theme={null}
curl -X POST "https://api.perplexity.ai/v1/agent" \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "What is Apple trading at right now, and what is its latest market cap?",
"tools": [{"type": "finance_search"}],
"max_steps": 1,
"max_output_tokens": 1024
}'
```
```json theme={null}
{
"id": "resp_541684d6-cc46-4115-9137-bb387088bc32",
"object": "response",
"model": "perplexity/sonar",
"status": "completed",
"created_at": 1777645562,
"completed_at": 1777645562,
"output": [
{
"type": "finance_results",
"categories": ["quote"],
"tickers": ["AAPL"],
"results": [
{
"category": "quote",
"tickers": ["AAPL"],
"content": "## AAPL Quote\n| symbol | name | timestamp | market_status | price | currency | change | changesPercentage | marketCap | pe | eps | volume | dayLow | dayHigh | yearLow | yearHigh | previousClose | open |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| AAPL | Apple Inc. | 2026-05-01 14:26:00 UTC | open | 285.74 | USD | 14.39 | 5.30 | 4,194,988,943,600 | 34.51 | 8.28 | 29,155,124 | 278.37 | 287.21 | 193.25 | 288.62 | 271.35 | 278.86 |",
"sources": [
"https://www.perplexity.ai/finance/AAPL/historical-data",
"https://www.perplexity.ai/finance/AAPL"
]
}
]
},
{
"type": "message",
"id": "msg_d8c03075-799d-4d4d-8feb-cc95824db262",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "Apple (AAPL) is currently trading at **$285.74** per share, up about 5.30% on the day. Its latest market capitalization is approximately **$4.19 trillion**.",
"annotations": [],
"logprobs": []
}
]
}
],
"tools": [{"type": "finance_search"}],
"max_output_tokens": 8192,
"tool_choice": "auto",
"parallel_tool_calls": true,
"usage": {
"input_tokens": 7575,
"output_tokens": 75,
"total_tokens": 7650,
"cost": {
"currency": "USD",
"input_cost": 0.00189,
"output_cost": 0.00019,
"tool_calls_cost": 0.005,
"total_cost": 0.00708
},
"tool_calls_details": {
"finance_search": {
"invocation": 1
}
}
}
}
```
### Single-Company Historical Lookups
Use this for a single company's historical figures or basic questions that benefit from both structured finance data and web context. GPT-5.5 is strong at simple web search and token-efficient for historical lookups.
```python Python theme={null}
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="openai/gpt-5.5",
input="What was Microsoft's revenue last fiscal year, and how did it compare with the prior year?",
tools=[
{"type": "web_search"},
{"type": "finance_search"},
{"type": "fetch_url"}
],
max_steps=5,
max_output_tokens=2048,
reasoning={"effort": "low"}
)
for item in response.output:
if item.type == "message":
print(item.content[0].text)
```
```bash cURL theme={null}
curl -X POST "https://api.perplexity.ai/v1/agent" \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.5",
"input": "What was Microsoft revenue last fiscal year, and how did it compare with the prior year?",
"tools": [
{"type": "web_search"},
{"type": "finance_search"},
{"type": "fetch_url"}
],
"max_steps": 5,
"max_output_tokens": 2048,
"reasoning": {"effort": "low"}
}'
```
```json theme={null}
{
"id": "resp_1be7ab7e-0dda-4949-9578-1462f9557a6b",
"object": "response",
"model": "openai/gpt-5.5",
"status": "completed",
"created_at": 1777645563,
"completed_at": 1777645563,
"output": [
{
"type": "finance_results",
"categories": ["financials"],
"tickers": ["MSFT"],
"results": [
{
"category": "financials",
"tickers": ["MSFT"],
"content": "## MSFT FY 2024\n| date | period | income_statement_total_revenues |\n| --- | --- | --- |\n| 2024-06-30 | 2024 FY | 245,122,000,000 |",
"sources": [
"https://www.perplexity.ai/finance/MSFT/financials?period=annual&category=INCOME_STATEMENT&fromYear=2024&toYear=2024"
]
}
]
},
{
"type": "finance_results",
"categories": ["financials"],
"tickers": ["MSFT"],
"results": [
{
"category": "financials",
"tickers": ["MSFT"],
"content": "## MSFT FY 2025\n| date | period | income_statement_total_revenues |\n| --- | --- | --- |\n| 2025-06-30 | 2025 FY | 281,724,000,000 |",
"sources": [
"https://www.perplexity.ai/finance/MSFT/financials?period=annual&category=INCOME_STATEMENT&fromYear=2025&toYear=2025"
]
}
]
},
{
"type": "message",
"id": "msg_99ccfbfd-bce8-4b9b-b412-b01ef45c7842",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "Microsoft's revenue in its last completed fiscal year, **FY2025 ended June 30, 2025**, was **$281.724 billion**.\n\nCompared with the prior year, **FY2024 revenue was $245.122 billion**, so Microsoft revenue increased by:\n\n- **$36.602 billion**\n- **About 14.9% year over year**",
"annotations": [],
"logprobs": []
}
]
}
],
"tools": [
{"type": "web_search"},
{"type": "fetch_url"},
{"type": "finance_search"}
],
"max_output_tokens": 8192,
"tool_choice": "auto",
"parallel_tool_calls": true,
"usage": {
"input_tokens": 12522,
"input_tokens_details": {
"cached_tokens": 3840,
"cache_read_input_tokens": 3840
},
"output_tokens": 500,
"total_tokens": 13022,
"cost": {
"currency": "USD",
"input_cost": 0.04341,
"cache_read_cost": 0.00192,
"output_cost": 0.015,
"tool_calls_cost": 0.01,
"total_cost": 0.07033
},
"tool_calls_details": {
"finance_search": {
"invocation": 2
}
}
}
}
```
### Multi-Step Financial Research
Use this for cross-company comparisons, longer historical investigations, and analysis that needs several tool calls across financial statements, filings, transcripts, and web sources. Opus performs best on complex multi-step reasoning when paired with the full tool suite.
```python Python theme={null}
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="anthropic/claude-opus-4-7",
input="Compare Apple, Microsoft, and Alphabet on revenue growth, margin trends, and management commentary over the last three fiscal years.",
tools=[
{"type": "web_search"},
{"type": "finance_search"},
{"type": "fetch_url"}
],
max_steps=10,
max_output_tokens=4096
)
for item in response.output:
if item.type == "message":
print(item.content[0].text)
```
```bash cURL theme={null}
curl -X POST "https://api.perplexity.ai/v1/agent" \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-opus-4-7",
"input": "Compare Apple, Microsoft, and Alphabet on revenue growth, margin trends, and management commentary over the last three fiscal years.",
"tools": [
{"type": "web_search"},
{"type": "finance_search"},
{"type": "fetch_url"}
],
"max_steps": 10,
"max_output_tokens": 4096
}'
```
```json theme={null}
{
"id": "resp_466bc636-cbad-43ce-9f66-c8b296712f05",
"object": "response",
"model": "anthropic/claude-opus-4-7",
"status": "completed",
"created_at": 1777645564,
"completed_at": 1777645564,
"output": [
{
"type": "finance_results",
"categories": ["financials"],
"tickers": ["AAPL", "MSFT", "GOOGL"],
"results": [
{
"category": "financials",
"tickers": ["AAPL", "MSFT", "GOOGL"],
"content": "## AAPL FY 2025\n| date | period | total_revenues | gross_profit | operating_profit | net_income | gross_margin | operating_margin | net_margin |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| 2025-09-27 | 2025 FY | 416,161,000,000 | 195,201,000,000 | 133,050,000,000 | 112,010,000,000 | 0.47 | 0.32 | 0.27 |\n\n## MSFT FY 2025\n| 2025-06-30 | 2025 FY | 281,724,000,000 | 193,893,000,000 | 128,528,000,000 | 101,832,000,000 | 0.69 | 0.46 | 0.36 |\n\n## GOOGL FY 2025\n| 2025-12-31 | 2025 FY | 402,836,000,000 | 240,301,000,000 | 129,039,000,000 | 132,170,000,000 | 0.60 | 0.32 | 0.33 |"
}
]
},
{
"type": "finance_results",
"categories": ["financials"],
"tickers": ["AAPL", "MSFT", "GOOGL"],
"results": [
{
"category": "financials",
"content": "## AAPL FY 2024\n| 2024-09-28 | 2024 FY | 391,035,000,000 | ... | 0.46 | 0.32 | 0.24 |\n\n## MSFT FY 2024\n| 2024-06-30 | 2024 FY | 245,122,000,000 | ... | 0.70 | 0.45 | 0.36 |\n\n## GOOGL FY 2024\n| 2024-12-31 | 2024 FY | 350,018,000,000 | ... | 0.58 | 0.32 | 0.29 |"
}
]
},
{
"type": "finance_results",
"categories": ["financials"],
"tickers": ["AAPL", "MSFT", "GOOGL"],
"results": [
{
"category": "financials",
"content": "## AAPL FY 2023 — total revenue 383,285,000,000 (GM 0.44 / OpM 0.30 / NM 0.25)\n## MSFT FY 2023 — total revenue 211,915,000,000 (GM 0.69 / OpM 0.42 / NM 0.34)\n## GOOGL FY 2023 — total revenue 307,394,000,000 (GM 0.57 / OpM 0.27 / NM 0.24)"
}
]
},
{
"type": "finance_results",
"categories": ["transcript"],
"tickers": ["AAPL", "MSFT", "GOOGL"],
"results": [
{
"category": "transcript",
"tickers": ["AAPL"],
"content": "AAPL Q2 2026: Revenue $111.184B (est. $109.46B), EPS $2.01 (est. $1.92). 17% revenue growth in March quarter; June guide +14-17%. GM guide 47.5-48.5%. Management flagged rising memory costs as an increasing headwind. Accelerating AI investment via Apple Intelligence; install base 2.5B devices.",
"sources": ["https://www.perplexity.ai/finance/AAPL/earnings"]
},
{
"category": "transcript",
"tickers": ["MSFT"],
"content": "MSFT Q3 2026: Revenue $82.886B (est. $81.44B), EPS $4.27 (est. $4.07). Revenue +18% YoY; AI ARR reached $37B (+123% YoY). CapEx >$40B next quarter, ~$190B for CY2026. Capacity-constrained through 2026. Expects double-digit revenue and operating-income growth in FY27.",
"sources": ["https://www.perplexity.ai/finance/MSFT/earnings"]
},
{
"category": "transcript",
"tickers": ["GOOGL"],
"content": "GOOGL Q1 2026: Revenue $109.896B (est. $106.98B), EPS $5.11 (est. $2.64). 22% revenue growth; Search +19%, Cloud +63%. Operating margin 36.1%. 2026 CapEx raised to $180-190B; 2027 CapEx to significantly increase. Cloud margin headwind from Wiz acquisition.",
"sources": ["https://www.perplexity.ai/finance/GOOGL/earnings"]
}
]
},
{
"type": "message",
"id": "msg_90e83fe4-f020-47f0-990e-f82aa0b655da",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "# Apple vs. Microsoft vs. Alphabet — 3-Year Comparison\n\n## 1. Revenue Growth\n| Company | FY2023 | FY2024 | FY2025 | 2-yr CAGR | YoY FY25 |\n|---|---|---|---|---|---|\n| Apple (AAPL) | $383.3B | $391.0B | $416.2B | +4.2% | +6.4% |\n| Microsoft (MSFT)| $211.9B | $245.1B | $281.7B | +15.3% | +14.9% |\n| Alphabet (GOOGL)| $307.4B | $350.0B | $402.8B | +14.5% | +15.1% |\n\n## 2. Margin Trends\n- Apple: GM 44% → 47%, OpM steady ~32%, NM 25% → 27%.\n- Microsoft: GM ~69% (slightly compressed by AI capex), OpM 42% → 46%, NM 34% → 36%.\n- Alphabet: GM 57% → 60%, OpM 27% → 32% (largest expansion), NM 24% → 33%.\n\n## 3. Management Commentary (latest calls)\n- Apple (Q2 FY26): Revenue +17%, June guide +14-17%; flagging memory-cost headwind.\n- Microsoft (Q3 FY26): Revenue +18%; AI ARR $37B (+123%); CY26 capex ~$190B.\n- Alphabet (Q1 2026): Revenue +22%; Cloud +63%; CY26 capex raised to $180-190B; 2027 capex to significantly increase.\n\n## Bottom Line\n- Revenue growth: Microsoft (closely followed by Alphabet)\n- Margin level: Microsoft\n- Margin expansion: Alphabet\n- Capital intensity: Apple is lightest; MSFT and GOOGL each spending $180-190B on 2026 capex.\n\nKey tension: AI investment is fueling top-line acceleration (especially MSFT and GOOGL) but creating depreciation and component-cost headwinds that are starting to weigh on gross margins.",
"annotations": [],
"logprobs": []
}
]
}
],
"tools": [
{"type": "web_search"},
{"type": "fetch_url"},
{"type": "finance_search"}
],
"max_output_tokens": 8192,
"tool_choice": "auto",
"parallel_tool_calls": true,
"usage": {
"input_tokens": 61887,
"input_tokens_details": {
"cached_tokens": 36778,
"cache_creation_input_tokens": 25100,
"cache_read_input_tokens": 36778
},
"output_tokens": 3456,
"total_tokens": 65343,
"cost": {
"currency": "USD",
"input_cost": 0.00005,
"cache_creation_cost": 0.15688,
"cache_read_cost": 0.01839,
"output_cost": 0.0864,
"tool_calls_cost": 0.02,
"total_cost": 0.28172
},
"tool_calls_details": {
"finance_search": {
"invocation": 4
}
}
}
}
```
## Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------- |
| `type` | string | Yes | Must be `"finance_search"`. |
## Response Shape
When `finance_search` runs, the response can include `finance_results` output items before the final assistant message. Each `finance_results` item includes the requested finance categories, ticker symbols, structured content, and source URLs when available. The final `usage` object includes token counts, cost details, and `tool_calls_details.finance_search.invocation` when tool-call usage is reported.
```json theme={null}
{
"output": [
{
"type": "finance_results",
"categories": ["quote"],
"tickers": ["NVDA"],
"results": [
{
"category": "quote",
"tickers": ["NVDA"],
"content": "Structured quote data returned by the finance search tool.",
"sources": [
"https://www.perplexity.ai/finance/NVDA"
]
}
]
},
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The answer generated from finance data."
}
]
}
],
"usage": {
"tool_calls_details": {
"finance_search": {
"invocation": 1
}
}
}
}
```
## Pricing
`finance_search` is billed at **\$5 per 1,000 invocations**. Model token usage is billed separately according to Agent API token pricing.
Pricing follows the same pattern as other tool calls: pay for invocations plus model tokens. See [Pricing](/docs/getting-started/pricing).
## Next Steps
Search the web for source-grounded context.
Fetch full content from known URLs.
Search for professionals and employees.
Get started with the Agent API.