> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> The Financial Datasets API is served at https://api.financialdatasets.ai. Authenticate with the `X-API-KEY` header; create keys at https://financialdatasets.ai. Agents can open and fund their own account without a dashboard: see https://docs.financialdatasets.ai/agents.md.
> Tool-using agents can call Financial Datasets without writing code through the hosted MCP server at https://mcp.financialdatasets.ai/.
> The OpenAPI spec at https://financialdatasets.ai/openapi.json is the source of truth for request and response schemas.
> The index of every docs page is at https://docs.financialdatasets.ai/llms.txt. Append .md to any docs URL to get that page as Markdown.
# Introduction
> Ask a question in plain English and get the exact passages that answer it, each with a citation.
Use Search when the answer is written in a document rather than stored in a field: why a CFO resigned, how a company describes a risk, what changed in guidance this quarter. One `POST /search` replaces reading the filing yourself. To make a first request, start with the [Quickstart](/search/quickstart). This page covers how to write queries, how to scope them, and what comes back.
**Alpha.** Access is by invitation; callers without access receive a `404`. The request and response shapes may change during the alpha. Contact us to request access.
## Writing queries
`query` is the only required field.
An effective query is a topic of two to six words, such as `committee retainers` or `clawback policy`, with the company's ticker in `filters.identifiers`. The company may also be named in the query text, as in `committee retainers for CCI`. Include a year to restrict the search to that year's documents. A full question or a description of the overall task performs less well than the short form.
A query that names a company Search cannot identify is declined with a `422` rather than answered from other companies' documents. Sending `filters.identifiers` resolves it.
## Filter results
A filter is a constraint on which documents are searched. Nothing outside a filter is returned.
### Restrict to companies
`filters.identifiers` names the companies to search, by scheme: `ticker` or `cik`. A CIK may be sent without leading zeros. An identifier no listed company has is a `400` that names it.
### Restrict by date
`filters.date` is a window on the day a document became public: `after`, `before`, or both, as ISO days. Both bounds are inclusive.
When the query names no year and the request sends no window, only the newest document of each company in scope is searched. A year in the query, or a date window, keeps every document inside it in scope. Use a window when the question is about a period: "every proxy since 2024" is `"after": "2024-01-01"`.
```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
response = requests.post(
"https://api.financialdatasets.ai/search",
headers={"X-API-KEY": "your_api_key_here"},
json={
"query": "director attendance below 75% of board and committee meetings",
"filters": {
"identifiers": {"ticker": ["JPM", "BAC", "C", "WFC"]},
"date": {"after": "2024-01-01"},
},
"limit": 25,
},
)
```
```javascript JavaScript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const response = await fetch("https://api.financialdatasets.ai/search", {
method: "POST",
headers: { "X-API-KEY": "your_api_key_here", "Content-Type": "application/json" },
body: JSON.stringify({
query: "director attendance below 75% of board and committee meetings",
filters: {
identifiers: { ticker: ["JPM", "BAC", "C", "WFC"] },
date: { after: "2024-01-01" },
},
limit: 25,
}),
});
```
```bash cURL theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl -s -X POST "https://api.financialdatasets.ai/search" \
-H "Content-Type: application/json" \
-H "X-API-KEY: $FINANCIAL_DATASETS_API_KEY" \
-d '{
"query": "director attendance below 75% of board and committee meetings",
"filters": {
"identifiers": { "ticker": ["JPM", "BAC", "C", "WFC"] },
"date": { "after": "2024-01-01" }
},
"limit": 25
}'
```
## Output shape
One result per document, best first. Ten documents come back unless `limit` says otherwise; the most you can ask for is 100. A key that does not apply to a result is absent, never `null`.
**Example response** for `clawback policy for incentive compensation` with `filters.identifiers.ticker` of `["AAPL"]`
The excerpts below are shortened.
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"search_id": "48805604-29b5-431f-ae85-7a405d576984",
"results": [
{
"title": "Apple Inc · DEF 14A 2026",
"url": "https://www.sec.gov/Archives/edgar/data/320193/000130817926000008/aapl014016-def14a.htm",
"date": "2026-01-08",
"source": "sec.gov",
"excerpts": [
{
"text": "Recoupment of Compensation\nThe terms of all outstanding time-based and performance-based RSU awards held by our named executive officers in 2025 allow us to recoup any shares or other ...",
"citation": {
"document": "0001308179-26-000008",
"date": "2026-01-08",
"section": "Compensation > Compensation Discussion and Analysis > Governance and Other Considerations > Recoupment of Compensation",
"link": "https://www.sec.gov/Archives/edgar/data/320193/000130817926000008/aapl014016-def14a.htm#:~:text=Governance%20and%20Other,to%20limited%20exceptions."
},
"attributes": { "kind": "text" }
},
{
"text": "Executive Compensation Policies and Practices\nWe are committed to sound executive compensation policies and practices, as highlighted in the following table.\nProhibition on hedging, pledging, and short sales | ...",
"citation": {
"document": "0001308179-26-000008",
"date": "2026-01-08",
"section": "Compensation > Compensation Discussion and Analysis > Executive Compensation Policies and Practices",
"link": "https://www.sec.gov/Archives/edgar/data/320193/000130817926000008/aapl014016-def14a.htm#:~:text=We%20have%20robust%20stock%20ownership%20guidelines,annual%20risk%20assessment%20of%20our%20compensation%20program."
},
"attributes": { "kind": "table", "part": "1 of 2" }
}
],
"entities": [
{ "name": "Apple Inc", "identifiers": { "cik": "0000320193", "ticker": "AAPL" } }
],
"attributes": { "document_type": "DEF 14A" }
}
]
}
```
| Field | Meaning |
| - | - |
| `search_id` | The id of this search. Keep it when you report a result to us. |
| `results[]` | One document each: `title`, `url`, `date`, `source`, `excerpts`, `entities`, `attributes`. |
| `excerpts[]` | The passages that answer, verbatim, best first, at most 10. Each has its own `citation` and `attributes`. |
| `citation` | `document` is the document's id at its source, `date` the day it became public, `section` the location of the passage within the document, and `link` opens the document at the passage, highlighted. |
| `attributes.kind` | `text` or `table`. A passage that covers part of a table also carries `part`, for example `"1 of 2"`. |
| `entities[]` | The companies the result is about, with their `cik` and `ticker`. |
| `warnings[]` | What a partial answer is missing. Present only when something is. |
## Errors
| Status | When | Body |
| - | - | - |
| `400` | The body is not valid. | `error.message` names the field, for example `limit: Input should be less than or equal to 100`. |
| `404` | The caller does not have access during the alpha. | `{"error": "The endpoint /search does not exist."}` |
| `422` | The query names a company Search cannot identify. | `error.reason` is `ambiguous_symbol` or `unresolved_company`; `error.fix` says what to send. |
| `503` | Search is temporarily unavailable. | `error.message`. Try again shortly. |
## OpenAPI
````yaml POST /search
openapi: 3.0.1
info:
title: Financial Datasets API
description: >-
Stock market API with real-time and historical financial data for 27,000+
tickers over 30+ years. Financial statements, equity prices, insider trades,
SEC filings, and more.
version: 1.0.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
contact:
name: API Support
url: mailto:support@financialdatasets.ai
email: support@financialdatasets.ai
termsOfService: https://financialdatasets.ai/terms-of-use
servers:
- url: https://api.financialdatasets.ai/
description: Production server
security:
- X-API-KEY: []
tags:
- name: Financial Statements
description: Access to income statements, balance sheets, and cash flow statements
- name: Market Data
description: Real-time and historical price data
- name: Company Information
description: Company facts like ticker, name, and description
- name: Earnings
description: Earnings data and related information
- name: News
description: Real-time and historical news articles
- name: SEC Filings
description: SEC filings and regulatory documents
- name: Insider Trades
description: Insider trading activity and transactions
- name: Activist Ownership
description: Activist stakes from SEC Schedule 13D filings, in real time
- name: Beneficial Ownership
description: >-
Holders of more than 5% of a company's shares, from SEC Schedules 13D and
13G
- name: Insider Ownership
description: Insider ownership statements from SEC Forms 3 and 5
- name: Institutional Holdings
description: SEC-direct 13F equity holdings of institutional investment managers
- name: IPOs
description: >-
Upcoming IPOs from SEC registration statements (Form S-1), with extracted
pre-IPO financial statements
- name: Index Funds
description: >-
ETF and index-fund holdings, weights, and the funds that hold a given
security
- name: Financial Metrics
description: Financial ratios, metrics, and key performance indicators
- name: Macroeconomics
description: Real-time and historical macroeconomic data like interest rates
- name: KPIs
description: Sector-specific operational KPIs extracted from earnings releases.
- name: Agent Account
description: Self-serve account creation and funding for AI agents.
- name: Search
description: Search financial documents with one question and get cited passages back
paths:
/search:
post:
tags:
- Search
summary: Search financial documents
description: >-
Ask one question in plain English and get the passages of financial
documents that answer it, each with a citation that opens the document
at the passage. Alpha: access is by invitation.
operationId: search
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
example:
query: clawback policy for incentive compensation
filters:
identifiers:
ticker:
- AAPL
limit: 1
responses:
'200':
description: The passages that answer, one result per document
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
example:
search_id: 48805604-29b5-431f-ae85-7a405d576984
results:
- title: Apple Inc · DEF 14A 2026
url: >-
https://www.sec.gov/Archives/edgar/data/320193/000130817926000008/aapl014016-def14a.htm
date: '2026-01-08'
source: sec.gov
excerpts:
- text: >-
Governance and Other Considerations
Recoupment of Compensation
The terms of all outstanding time-based and
performance-based RSU awards held by our named
executive officers in 2025 allow us to recoup any
shares or other ...
citation:
document: 0001308179-26-000008
date: '2026-01-08'
section: >-
Compensation > Compensation Discussion and Analysis
> Governance and Other Considerations > Recoupment
of Compensation
link: >-
https://www.sec.gov/Archives/edgar/data/320193/000130817926000008/aapl014016-def14a.htm#:~:text=Governance%20and%20Other,to%20limited%20exceptions.
attributes:
kind: text
entities:
- name: Apple Inc
identifiers:
cik: '0000320193'
ticker: AAPL
attributes:
document_type: DEF 14A
'400':
description: The body is not valid. The message names the field.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchErrorResponse'
example:
error:
message: 'limit: Input should be less than or equal to 100'
'401':
$ref: '#/components/responses/UnauthorizedError'
'402':
$ref: '#/components/responses/PaymentRequiredError'
'404':
description: The caller does not have access during the alpha
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: The endpoint /search does not exist.
'422':
description: >-
The question names a company the search cannot identify. Send
filters.identifiers.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRefusalResponse'
example:
search_id: e38104d5-6bd7-4d82-bc4e-0a21179d1f77
error:
reason: unresolved_company
message: A company named in the query matched no listing, or several.
fix: Send filters.identifiers.
'503':
description: Search is temporarily unavailable. Try again shortly.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchErrorResponse'
example:
search_id: e38104d5-6bd7-4d82-bc4e-0a21179d1f77
error:
message: Search is temporarily unavailable. Try again shortly.
components:
schemas:
SearchRequest:
type: object
required:
- query
properties:
query:
type: string
minLength: 1
maxLength: 300
description: One question in plain English, 1 to 300 characters.
filters:
type: object
description: >-
Constraints on which documents are searched. Nothing outside a
filter is returned.
properties:
identifiers:
type: object
description: >-
The companies the search is about, by scheme. Results come only
from these companies. An identifier no listed company has is a
400.
properties:
ticker:
type: array
items:
type: string
description: Ticker symbols, for example ["AAPL", "MSFT"].
cik:
type: array
items:
type: string
description: SEC Central Index Keys. Leading zeros are optional.
date:
type: object
description: >-
A window on the document's date, the day it became public. Both
bounds are inclusive. Send either or both. A window keeps every
document inside it in scope.
properties:
after:
type: string
format: date
description: Only documents made public on or after this day.
before:
type: string
format: date
description: Only documents made public on or before this day.
limit:
type: integer
minimum: 1
maximum: 100
default: 10
description: How many results to return. A result is one document.
SearchResponse:
type: object
required:
- search_id
- results
properties:
search_id:
type: string
format: uuid
description: The id of this search. Keep it when you report a result.
results:
type: array
description: One result per document, best first. At most `limit`.
items:
$ref: '#/components/schemas/SearchResult'
warnings:
type: array
description: What a partial answer is missing. Absent when nothing is.
items:
type: object
properties:
type:
type: string
description: A code you can branch on.
message:
type: string
description: What is missing.
fix:
type: string
description: What to send instead.
SearchErrorResponse:
type: object
properties:
search_id:
type: string
format: uuid
description: >-
The id of this search. Absent when the request was refused before a
search began.
error:
type: object
properties:
message:
type: string
description: What is wrong. A 400 names the field.
SearchRefusalResponse:
type: object
required:
- search_id
- error
properties:
search_id:
type: string
format: uuid
error:
type: object
required:
- reason
- message
- fix
properties:
reason:
type: string
enum:
- ambiguous_symbol
- unresolved_company
description: Why the search was refused. A code you can branch on.
message:
type: string
description: What the question left unclear.
fix:
type: string
description: What to send so the search can run.
SearchResult:
type: object
description: One document, with the passages in it that answer the question.
required:
- title
- url
- date
- source
- excerpts
- entities
- attributes
properties:
title:
type: string
description: >-
The company and the document, for example "Apple Inc · DEF 14A
2026".
url:
type: string
description: The document itself.
date:
type: string
format: date
description: The day the document became public.
source:
type: string
description: The site the document came from. Today always "sec.gov".
excerpts:
type: array
description: The passages of this document that answer, best first. At most 10.
items:
$ref: '#/components/schemas/SearchExcerpt'
entities:
type: array
description: The companies the result is about.
items:
$ref: '#/components/schemas/SearchEntity'
attributes:
type: object
description: What is true of the document.
properties:
document_type:
type: string
description: The kind of document, for example "DEF 14A".
ErrorResponse:
type: object
properties:
error:
type: string
description: A short error message.
message:
type: string
description: A more detailed error message.
SearchExcerpt:
type: object
description: >-
One passage of the document that answers the question, with its own
citation.
required:
- text
properties:
text:
type: string
description: The passage, verbatim from the document.
citation:
$ref: '#/components/schemas/SearchCitation'
attributes:
type: object
description: What is true of this passage.
properties:
kind:
type: string
enum:
- text
- table
description: Whether the passage is running text or a table.
part:
type: string
description: >-
The part of a table this passage covers, for example "1 of 2".
Absent for text and for a table returned whole.
SearchEntity:
type: object
description: A company the result is about.
required:
- name
- identifiers
properties:
name:
type: string
description: The company's name.
identifiers:
type: object
description: >-
The company's identifiers by scheme. The same schemes
filters.identifiers accepts.
properties:
cik:
type: string
description: The SEC Central Index Key, zero-padded to 10 digits.
ticker:
type: string
description: The ticker symbol.
SearchCitation:
type: object
description: Where a passage was read, and the link that opens the document there.
required:
- document
- date
properties:
document:
type: string
description: >-
The document's id at its source: the accession number for an SEC
filing.
date:
type: string
format: date
description: The day the document became public.
section:
type: string
description: >-
The headings above the passage, outermost first. Absent when the
passage sits under no heading.
link:
type: string
description: >-
Opens the document at the passage, highlighted, or the document
itself when a highlighted link is not available.
responses:
UnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Unauthorized
message: Invalid API key provided
PaymentRequiredError:
description: The request requires a paid subscription
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment Required
message: >-
This endpoint requires a paid subscription. Please upgrade your
plan.
securitySchemes:
X-API-KEY:
type: apiKey
name: X-API-KEY
description: API key for authentication.
in: header
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.