---
title: "Search financial documents"
method: POST
path: "/search"
tags: ["Search"]
---

# Search financial documents

`POST /search`

## Request

- Base URL: `https://api.financialdatasets.ai`
- URL: `https://api.financialdatasets.ai/search`
- Auth: API key in header `X-API-KEY`

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. Two kinds of document are read: proxy statements (DEF 14A) and current reports (8-K) with their exhibits. Alpha: access is by invitation.

## Request body

- SearchRequest
  - `query` string, required: One question in plain English, 1 to 300 characters.
  - `filters` object: Constraints on which documents are searched. Nothing outside a filter is returned.
    - `identifiers` object: The companies the search is about, by scheme. Results come only from these companies. An identifier no listed company has is a 400.
      - `ticker` string[]: Ticker symbols, for example ["AAPL", "MSFT"].
      - `cik` string[]: SEC Central Index Keys. Leading zeros are optional.
    - `date` object: 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.
      - `after` string, date: Only documents made public on or after this day.
      - `before` string, date: Only documents made public on or before this day.
    - `document_type` string[]: The kinds of document to read, as a result's attributes.document_type names them. An amendment reads with its base form. Absent, every kind the question names is read, else every kind.
  - `limit` integer: How many results to return. A result is one document.

## Response `200`

The passages that answer, one result per document

- SearchResponse
  - `search_id` string, uuid, required: The id of this search. Keep it when you report a result.
  - `results` SearchResult[], required: One result per document, best first. At most `limit`.
    - `title` string, required: The company and the document, for example "Apple Inc · DEF 14A 2026". An exhibit names its filing and itself: "Apple Inc · 8-K 2026-07-30 · EX-99.1".
    - `url` string, required: The document itself.
    - `date` string, date, required: The day the document became public.
    - `source` string, required: The site the document came from. Today always "sec.gov".
    - `excerpts` SearchExcerpt[], required: The passages of this document that answer, best first. At most 10.
      - `text` string, required: The passage, verbatim from the document.
      - `citation` SearchCitation: Where a passage was read, and the link that opens the document there.
        - `document` string, required: The document's id at its source: the accession number for an SEC filing.
        - `date` string, date, required: The day the document became public.
        - `section` string: The headings above the passage, outermost first. Absent when the passage sits under no heading.
        - `link` string: Opens the document at the passage, highlighted, or the document itself when a highlighted link is not available.
      - `attributes` object: What is true of this passage.
        - `kind` 'text' | 'table': Whether the passage is running text or a table.
        - `part` string: The part of a table this passage covers, for example "1 of 2". Absent for text and for a table returned whole.
    - `entities` SearchEntity[], required: The companies the result is about.
      - `name` string, required: The company's name.
      - `identifiers` object, required: The company's identifiers by scheme. The same schemes filters.identifiers accepts.
        - `cik` string: The SEC Central Index Key, zero-padded to 10 digits.
        - `ticker` string: The ticker symbol.
    - `attributes` object, required: What is true of the document.
      - `document_type` string: The kind of document, for example "DEF 14A" or "8-K".
      - `exhibit` string: The exhibit this document is, for example "EX-99.1". Absent when the document is the filing itself.
      - `items` string[]: For a current report, the codes of the events it reports, for example ["2.02", "9.01"]. Absent for other kinds.
  - `warnings` object[]: What a partial answer is missing. Absent when nothing is.
    - `type` string: A code you can branch on.
    - `message` string: What is missing.
    - `hint` string: What to send instead.

## Other responses

- `400`: The body is not valid. The message names the field.
- `401`: Unauthorized
- `402`: The request requires a paid subscription
- `404`: The caller does not have access during the alpha
- `422`: The question names a company the search cannot identify. Send filters.identifiers.
- `503`: Search is temporarily unavailable. Try again shortly.

## Changes

- **2026-11-03** `5872e134b56c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/financialdatasets/apis/financial-datasets-api/changes/search/post.md)

---

[API](https://skmtc.dev/financialdatasets/apis/financial-datasets-api.md) - [All operations](https://skmtc.dev/financialdatasets/apis/financial-datasets-api/llms.txt) - [OpenAPI document](https://skmtc.dev/financialdatasets/apis/financial-datasets-api/revisions/42ba45d24472?raw)