Sessions, paging and records

Identifiers and lifetime

• search_id matches ^srch_[0-9A-Za-z]{16}$; record_id matches ^rec_[0-9A-Za-z]{16}$. Both are minted server-side and scoped to your account.
• A session lives 24 hours after its last use. Every more, update and record action touches it. An expired session answers 410 session_expired; a purged or malformed id answers 404 record_unknown. Either way: execute again.
• A record id resolves for any key of the same account, so a worker may open a record that another worker found.

The execute envelope

Execute, more and update all return ExecuteResponse:

{
  "search_id": "srch_…",           // stable for the session
  "capability": "hotels.search",
  "results": [ { "record_id": "rec_…", "title": "…", "url"?: "…", "snippet"?: "…", ...documented keys } ],
  "result_count": 10,              // length of results[] on this page
  "has_more": true,                // another page exists (paged capabilities only)
  "filters"?: [ { "id": "flt_…", "label": "…", "group": "…" } ],   // shopping.search only
  "next": { "url": "/v1/follow-up", "actions": ["more","update"], "example": { … } | null },
  "record_actions": ["details"],
  "notes"?: [ "…" ],               // provider-shaped hints: fallbacks used, truncation, limits
  "charged_credits": 4,
  "balance": { "used": 91, "cap": 15000, "period_end": "2026-10-19T17:35:40.303Z" | null }
}

record_id and title are guaranteed on every record. Everything else on a record is the documented tier for that capability (listed on its reference page) and can be absent when the source has no value. Clients must ignore unknown keys.

Paging with more

• Loop on has_more, not on result_count: a server-side filter (hotel rating, place radius, real-estate caps) can leave a page empty while another page exists. Bound the loop (for example at 10 pages).
• more appends to the session: earlier record ids stay valid. Provider caps (GitHub's 1,000 results, 20 provider pages for places) end paging before the provider total.
• Capabilities that hold the whole result set locally (recipes.search, fitness.exercises, transit.routes, companies.financials, legal.read) serve more without a provider call and charge 0.
• Single-result capabilities (web.read, weather.forecast, navigation.route, navigation.matrix, flights.search, markets.quote, trends.search) refuse more with 400 invalid_request; their next.actions never contains it.

Changing the query with update

update merges params into the stored query, re-validates the result against the full request schema, resets paging, keeps the search_id and replaces the stored records: earlier record ids of that session are gone. It is billed like a fresh search for paid sources.

• shopping.search: a change of query, country, language or location clears filter_id; sending a filter with such a change is refused. Filters come from the current search only.
• recipes.search: one supplied selector replaces all four.
• markets.quote and trends.search: update is a billed refresh with the merged parameters (there is no separate refresh action).

Record actions and details

Record actions (details everywhere it is listed, plus read, transcript, financials, revenue_breakdown) return RecordFollowUpResponse:

{ "record_id": "rec_…", "action": "details", "detail": <provider-shaped>, "links": [{ "label", "url" }],
  "cached"?: true, "charged_credits": 0, "balance": { … } }

• The first call fetches (billed as the capability page states) and caches; a repeat is served from the cache with cached: true and charged_credits: 0. Cached repeats still pass admission (one call per account at a time).
• Cache-only capabilities store the detail at search time and never re-fetch it: news.search, trends.search, markets.quote, jobs.search, fitness.exercises, transit.routes, legal.search, legal.read, and the details of companies.financials.
• Three actions return a typed next request inside the payload: flights.search details may carry return_search: { capability, params }; legal.search records carry full_text: { capability: "legal.read", params }; companies.financials fact views carry continuation: { capability, body }. Execute that request as-is.