> ## 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. # Best Practices > Tune a working Search request: the query, the filters, the result count, and how to read what comes back. This guide is for a request that already returns results. It describes how to improve their precision: the form of the query, the use of filters, the number of documents requested, and how to diagnose a result that does not meet expectations. ## Send the ticker with every query Specify the company in `filters.identifiers`, by ticker or CIK, whenever it is known. The search is then confined to that company's documents: no passage from another company is returned, and the most relevant passages of the intended company rank first. Of all the adjustments on this page, this one has the largest effect on precision. ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "query": "committee retainers", "filters": { "identifiers": { "ticker": ["CCI"] } } } ``` A list of tickers runs the same query over each of those companies. Omit the filter only when the company that holds the answer is not known. ## Shape of a good query An effective query is a topic of two to six words, with the company in `filters.identifiers`. The topic is the subject of the passage sought, stated as it would appear in a sentence: "committee retainers", "clawback policy", "stock ownership guidelines", "say-on-pay vote", "lead independent director". Include a year to restrict the search to that year's documents. * `committee retainers` with ticker `CCI` * `special committee formed` with ticker `TSLA` * `CEO pay ratio` with ticker `ABBV` * `special committee formed 2025` with ticker `TSLA` Three forms work less well: a full question (`How did Crown Castle pay the directors on its committees?`), a single word (`retainers`), and a description of the overall task. The company may also be named in the query text, as in `committee retainers for CCI`, when sending a filter is impractical. The remaining fields serve specific needs: | Field | Reason | | - | - | | `filters.date` | The question is about a period, not about what the company says today. | | `limit` | More than 10 documents are needed, up to 100, or fewer are wanted to conserve context. | ## Diagnosing a result When a result does not meet expectations, change one element of the request and compare. Changing two elements at once makes it impossible to attribute the improvement. The `title` identifies the document, the `date` identifies the year, and `citation.section` locates the passage within the document. A correct section with a weak excerpt calls for a different wording of the query; an incorrect document calls for a filter. Companies describe the same practice in different terms: "clawback" and "recoupment", "special committee" and "ad hoc committee". When a query returns nothing relevant, submit the alternative term as a second request. A filter is a constraint, not a preference. Apply `filters.identifiers` or `filters.date` when a document outside the constraint would be unacceptable. A mere preference for a company or a year belongs in the query text. ## Ask a universe question To run one query across a set of companies, list them in `filters.identifiers` and raise `limit`. Results are drawn only from those companies, one result per document, so the number of results is the number of documents that contain a relevant passage. ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "query": "additional fees for service on an ad hoc committee", "filters": { "identifiers": { "ticker": ["JPM", "BAC", "C", "WFC"] } }, "limit": 100 } ``` `limit` accepts at most 100. For a universe larger than that, submit the identifiers in batches and combine the results. An identifier that matches no listed company returns a `400` naming it, so a mistaken ticker is reported rather than silently omitted from the universe. ## Set the time window on purpose When the query names no year and no `filters.date` is sent, only the most recent document of each company is searched. This default suits questions about a company's current disclosure. For questions about a period, send a window: ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "filters": { "date": { "after": "2024-01-01" } } } ``` A window keeps every document within it in scope, so a question spanning a company's last three proxy statements returns passages from all three. ## Quote the excerpt, cite the link An excerpt's `text` is reproduced verbatim from the document and may be quoted as such. Its `citation.link` opens the document at that passage with the text highlighted, so a reader can verify the quotation against the source. Retain `citation.document`, `citation.date` and `citation.section` alongside the quotation: together they identify the document, its date, and the location of the passage. A passage taken from a table carries `attributes.kind: "table"` and, when it covers part of a table, `attributes.part`. The parts, read in order, give the whole table. ## Maintain a reference set of queries Record the queries used while tuning, around ten that represent the actual work. Run the full set after each change, so that an improvement to one query is not accepted at the cost of several others. Store each response's `search_id` with its query. When a result is incorrect or a passage is missing, the id and the query allow us to reproduce the case exactly. ## Common mistakes | Mistake | Do this instead | | - | - | | A full question as the query | A topic of two to six words, with the ticker in `filters.identifiers`. | | Omitting the ticker when the company is known | Send it in `filters.identifiers`. | | A description of the whole task as the query | One short query per item sought. `query` accepts at most 300 characters. | | Retrying a `422` | Send `filters.identifiers` with the company; the same query then succeeds. Only a `503` warrants a retry. | | Expecting a prevalence count at the default `limit` | Set `limit` to 100 and submit the universe in batches. `limit` counts documents. | | Judging a result by the excerpt alone | Review `title`, `date` and `citation.section` as well. They indicate whether the query or a filter should change. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.