Guides

The reference tells you what every parameter does. These tell you which ones matter, and what happens when you get them wrong.

Recipes 24 worked queries for real tasks — what comes back, and how each one breaks unattended. Choosing a ranking mode Keyword, semantic or hybrid — and why the right answer depends on who wrote the query. Stories for context windows The single biggest token saving available here, and when it is the wrong call. Time windows Why omitting from is expensive, what a plan bounds, and how to pick a range. Planning a credit budget Rate limits and backoff Two conditions share one status code. Only one is worth waiting for. Entity and signal filtering Finding coverage by what it is about rather than by what words it uses. Reading relationships Who is reported alongside an entity, how two connect and what changed, and how to say so without claiming more than the reporting shows. Reading completeness Three fields say whether the index fully answered. Read them before concluding anything is absent. Building a news agent An end-to-end agent over MCP, and the prompt that makes it use the right tool. Monitoring a topic A watch the index runs for you, or a polling loop that does not duplicate, does not miss, and fits inside a credit budget. Evaluating coverage Measuring how much attention something got, with facets and outlet counts.

How these differ from the reference

The API reference is exhaustive and answers "what does this parameter do" — every field, every type, every default, generated straight from the OpenAPI document so it cannot drift from what the server actually accepts. These guides answer a different question: "which parameter, and why this one over the obvious alternative." A reference page will tell you mode accepts keyword, semantic or hybrid; the guide tells you that a query a model wrote should almost always be hybrid, because models paraphrase, and a query a person typed with an exact phrase in mind should not be. Neither page tries to be the other — the reference would be worse if it hedged every field with "it depends," and a guide that restated every type from the spec would just be a slower way to read the reference.

Which guide answers which question

My results look relevant individually but the same event shows up ten times: Stories for context windows — collapse before you rank, not after.
The same query returns different things depending on who or what sent it: Choosing a ranking mode — the split is whether a human or a model wrote the query, not the subject matter.
I keep getting fewer results than I expect for a wide date range: Time windows — a plan's archive depth clamps from silently unless you check for it.
My polling loop gets 429s under normal use, not just under load: Rate limits and backoff — one 429 is transient and one is not, and they share a status code.
Keyword filters return nothing because I don't know the exact spelling: Entity and signal filtering — facet the vocabulary before filtering on it.
I'm building something that runs without a human reading every result: Building a news agent and Monitoring a topic — an agent that chooses its own queries and a scheduled poll are different problems with different failure modes.
I need to say how much attention something got, not just find it: Evaluating coverage — outlet counts and facets measure this; result counts alone do not.
I want worked examples rather than a decision to make: Recipes — the same decisions above, already made, for two dozen specific tasks.

None of these guides is a substitute for reading the parameter it is about — each one links back to the reference section it depends on, and the reference is what to trust if the two ever disagree, since it is generated from the same document the server itself validates requests against.

If you only read two

Stories for context windows — the habit that most changes how well this API works for you.
Time windows — the parameter that most changes what a request costs, and what it returns.

Both are short by design — each is one specific habit rather than a survey — and both apply regardless of which endpoint or which client you are already using, which is why they are worth reading before any recipe below.