Skip to main content
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.
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:

​
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.
1

Review the title, date and section before the excerpt

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.
2

Try an alternative term

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.
3

Use filters to exclude, not to prefer

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.
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:
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. 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