Recipes
24 real tasks, each with the request that answers it — and, more usefully, what comes back, how it breaks once it is running unattended, and how to bend it into the neighbouring task you actually have.
/stories
/search
/top-headlines
If none of these fit
The recipes are patterns, not an API surface — every one of them is the same handful of endpoints with different parameters. If yours is not here, the pieces are:
- Which ranking mode — the choice that most changes what comes back, and it depends on whether a human or a model wrote the query.
- Whether to collapse into stories — almost always yes, if the results are going anywhere near a context window.
- How tightly to bound it — the parameter that most changes what a request costs.
- Which filter substitutes for the one you wish existed — usually an entity or a signal range rather than more words in the query.
Why nothing is listed under /top-headlines
Every recipe here is built on /stories or /search, and the gap above is real rather than
an oversight: /top-headlines answers a narrower question — what is most recent, not what is most
relevant — and every task collected here turned out to need relevance, a time window, or both, which
/search and /stories already cover. Reach for /top-headlines directly, without
a recipe, when the task is genuinely recency-only: a live ticker, or expanding one story's story_id
into its full article list rather than searching for it again. The reference
covers both.
Adapting the closest one instead of starting over
Most tasks that are not listed above are closer to one of these than they look, because the parameters that actually distinguish a recipe are few: the ranking mode, whether results collapse into stories, and which one or two filters do the narrowing. Read the recipe whose shape matches — a single subject watched continuously, a comparison across two slices, a one-off precise query — rather than the one whose task description uses the same words as yours. Executive mention tracking and competitive intelligence are the same pattern with a different entity filter, for instance, and neither page says so, because the pattern is more visible from outside both than from inside either.
| What the task looks like | Start from |
|---|---|
| Watching one named thing continuously | Executive mention tracking |
| Comparing two slices of the same event | Compare coverage across markets |
| A single precise, one-off pull | Precise time window analysis |
| Feeding a model rather than a person | Daily summary for a model |
| Detecting an absence rather than an event | Quiet period detection |
| Following one thing across many languages | Brand mentions across languages |
When two rows in the table above both look close, the tie-breaker is usually whether the task is a standing watch or a one-time pull. A standing watch needs the polling and deduplication guidance in the "running it for real" section of whichever recipe you start from; a one-time pull needs none of that and can drop the scheduling advice entirely. Recipes here do not separate the two explicitly, because in practice the request and the ranking choice are identical either way — only what you do with the response differs.