Skip to main content
A list of 10 results does not say whether 10 pages were found or 400, whether the German wording ran anywhere, or whether the date filter was applied. An agent that cannot see this repeats a weak search, and a reviewer cannot tell a careful search from a careless one. Every search here returns an account of itself with its results. An agent reads it to make its next search better, and a reviewer reads it to check the method.

Read why the list ended

counts says how many pages were found and why the others are not in the list. This response is cut to the reasons that are not 0.
Part of the response
Of 41 pages found, 3 came back. The ranking put 30 under its cut-off for relevance, and 8 were copies of a page already in the list. The numbers add up: found is returned plus every number in dropped. end_reason says why the list stopped where it did.

See what each datasource did

datasources_searched has one entry for each datasource that ran. This response is cut to one entry and to the fields that this section explains.
Part of the response
An entry says why the datasource ran, how its part of the search ended, and which of your wordings it ran. result_count is the number of results the datasource says it has, and result_count_kind says whether that number is exact, an estimate, or a lower_bound. filters_applied says for each filter whether the datasource applied it itself, native, or getclean applied it afterwards, emulated, with a line on how. Query operators such as a phrase in quotation marks are reported the same way in operators_applied.

Find what was not searched

A part of the request that could not be searched at all is a coverage gap. coverage_gaps names each one: a datasource, a wording, a site, or a language, with the reason. A gap is a fact to put in a report. “No German source was searched” is another finding than “no German source says so”.

Read the results that were dropped

The whole list is stored with the search, and get_search returns it at no charge. Its later pages have the results that were dropped, each with its dropped_reason.
Replace SEARCH_ID with the id of the search, and PAGE_TOKEN with the next_page_token of the page before. The SDKs ask for the next page as you loop.

See how the question was read

interpretation says how the question was understood: the phrases in quotation marks, the excluded words, the operators, and every wording that ran with the number of results it found on each datasource. If a spelling was corrected, the corrected wording ran beside yours, and the notice query_corrected says so. applied_request has the request as it ran, with every default written out.

Hand the method to a reviewer

A systematic review has to report each search as it was run, with its date and its counts. Send record_form, and the response has the search written up in record. plain writes it in plain words. prisma writes it in the PRISMA form, which is the form such reviews report in. A search is stored for 48 hours after its last use and for at most 30 days, so store the write-up with your own files.

Check what a receipt costs

The receipt is part of every search and adds nothing to its cost. get_search costs nothing, and the key needs the scope search:read. A search that sends view as compact returns a smaller response without the receipt.