Skip to main content
A search and 5 fetches are 6 calls and 6 turns of an agent. Most of those turns bring back what the agent could have asked for at the start: the outline of each page, or the passages that bear on its question. With contents in a search, the first results are fetched inside the call, and each is read the way you say.
Set contents.top to the number of results to fetch, from 1 to 10. This search returns 3 results and fetches the first one, with at most 8,000 characters of its text.
A fetched result has a record in contents. This response is cut to the first result and to its record.
201 Created
The page has more than 8,000 characters, so its outline came in place of a text cut at an arbitrary point. The section “Article 50” has 9,100 characters, and one more call reads it by its id. For that call, see Read the 2 sections you need from a 300-page document.

Choose how each result is read

contents takes the fields of a fetch. The record of a fetched result has its text as Markdown, or its outline. Any other format is a read of the stored record by its id, at no charge.

Get the evidence without the pages

The fields combine. This request searches in 4 wordings, puts official sources first, asks 4 questions of the first of them, fills a template of 5 fields from it, and returns no page text at all.
Request body
The response has, for the first result, its outline, the place of each passage that bears on a question, and the 5 fields, each with the words it was filled from. The agent has spent one call and has the evidence and the way back to it. It reads a section in full only where the evidence is thin.

Bound the text of the response

max_total_characters limits the text of the whole response, 40,000 characters unless you set it. The excerpts of the results come first. The fetched pages follow in rank order as long as they fit. A page that would pass the limit comes as its outline with the notice total_characters_cut, and its text stays in the record.

Give the fetches enough time

The fetches run inside the time of the search, which is wait_seconds. A search has 10 seconds by default, where a fetch on its own has 30. A search that fetches several pages or asks for model steps should set wait_seconds higher, up to 60, because the fetches share that time. A fetch that was not started by the end of that time makes no record. The outcome of the search is then partial with the reason fetches_missing, and the notice fetch_not_finished names the results. Fetch each of them with fetch_contents.

Read a fetched result again

The record of a fetched result is a stored record like any other. Its id works with get_section, list_blocks, highlight_contents, and the other calls on a record. After the fetch, each excerpt of the result also has the place where its words are in the record.

Check what the call costs

The call costs the search, and each fetch is charged as a fetch. A filled schema and a summary each cost one model step for each page, and so do highlights if a model has to judge one. Each record has its own cost. A result that was not fetched has fetch_cost: the most a fetch of it can cost with the fields of this request. An agent can read the price of going further before it pays it. The field is missing for a document whose number of pages is not known.