Skip to main content
A credit agreement of 300 pages is larger than the context of the agent that has to read it. Text that is cut at a fixed length loses the part that mattered, and a summary loses the wording. A fetch of such a source returns its outline first. Each row of the outline is a section with an id, so you can read 2 sections of the agreement and still know what the others are.

Get the outline before any text

Fetch the source with max_characters set to 0. The response has the outline and the facts of the source, and no text.
Replace SOURCE_URL with the address of a page or a document. The outline is the sections list. This response is cut to 4 of its rows.
201 Created
A row has the size of its section in characters, with everything under it. That number is what the read of the section will add to your context, so you can choose before you read. basis says where the sections come from. On a web page they are the page’s headings. In a document they are its own structure, or the outline of a PDF that has no structure. A scan has neither, and its outline is one row for each page. The outline has at least the top level of sections. Deeper levels come one whole level at a time, while the outline has at most 200 rows. If levels were left out, the notice sections_cut says so, and a read of a section lists the sections under it.

Read one section by its id

get_section returns the text of one section from the stored record. The source is not fetched again, and the call costs nothing.
Replace CONTENTS_ID with the id of the record. A section that is larger than max_characters, which is 20,000 if you send none, does not come cut in the middle. If it has sections under it, the response has its own first text and the rows of those sections, and you read each by its id. If it has none, the text is cut at the edge of a block, and next_page_token continues it. The text before the first heading is the section s0. On a source without headings, s0 is the whole text.

Let the questions choose the sections

If you know what you are looking for, you do not need to choose from the outline. Send your questions as highlights with the fetch. For a source that is larger than max_characters, the response then has the sections that contain a highlight, with the reason matching_sections, and the outline beside them. For the request and the marks, see Highlight the evidence for each question.

Read the tables of a section

To get only one kind of content from a section, list its blocks by kind. A block is one unit of the content, such as a paragraph, a heading, or a table. This request returns the tables of the section, each cell by cell.

Know how long the record is there

A record is stored for 48 hours after the last call that used it, and for at most 30 days. Each read of a section moves the 48 hours forward. expires_at in a response has the moment. A document that is too long to be read within one fetch comes back with the outcome partial and the notice upload_to_finish. Send its address to upload_contents, which reads the whole document as a job.