Recipes
Worked query patterns for tasks people actually build. Each one names the retrieval mode, the filters that matter, and the mistake that makes it return the wrong thing.
The four decisions every query comes down to
Nearly every recipe below is a combination of the same four choices, and getting them right matters far more than the exact phrasing of the query.
Retrieval mode. Keyword for identifiers, semantic for concepts, hybrid for anything a model composed. Outside English, keyword is rarely the right answer.
Clustered or not. Cluster when results feed a context window or an alert. Do not cluster when the duplicates are the thing you are studying.
Time bound. Always set one. An unbounded semantic query over a deep archive returns confident results anchored to nothing.
Outlet scope. The most under-used filter. Restricting to a known set of publishers is usually a better proxy for region, sector or editorial stance than any other field, and it makes sentiment comparisons meaningful instead of accidental.
Tasks
| Task | Mode | The thing that decides it |
|---|---|---|
| Track every mention of a brand, in every language you do not read | hybrid | Hybrid rather than keyword because brand names get transliterated, abbreviated and inflected differently in every language — a Latin-script query will not match the Devanagari or Cyrillic rendering of the same name, and keyword mode has no way to bridge that. |
| Detect layoff announcements as they are reported | semantic | Semantic mode is not optional here, because the vocabulary is the whole problem. |
| Ground a model answer in current reporting without wasting the context window | hybrid | The common mistake here is reaching for article search. |
| Stop one wire report arriving as forty results | hybrid | Syndication is structural, not incidental. |
| Build a morning digest someone will actually read | recent | A digest lives or dies on whether the reader trusts it to be complete without being repetitive, and story collapsing is what makes that possible. |
| Follow one story as coverage accumulates, without re-reading it | hybrid | Poll for what is new rather than re-querying the whole window, and keep the last-seen timestamp yourself, or save the topic query as a watch, which polls and keeps that position server-side. |
| Follow earnings coverage for a listed company | keyword | One of the few cases where keyword mode is the right answer. |
| Monitor a market whose language nobody on the team reads | semantic | Semantic mode lets you query in one language and match coverage in another, which is the only workable approach when nobody on the team can compose a query in the target language. |
| Compare how two markets covered the same event | semantic | The one recipe here that deliberately does not collapse to stories. |
| Catch supply chain disruption before it reaches the wires | semantic | The trade and domestic-language press leads the international wire on this by days. |
| Watch for regulatory action in a sector | hybrid | Regulators publish in bursts around decisions and consultations, then go quiet, so a short rolling window returns either a flood or nothing depending on where it lands. |
| Build a crypto news feed that is not mostly press releases | hybrid | Crypto coverage has an unusually high ratio of syndicated and promotional material to original reporting, so story collapsing matters more here than in almost any other subject. |
| Find coverage with a particular tone | hybrid | Every article carries a tone score derived from its language. |
| Follow a sector, but only in publications you trust | hybrid | The outlet filter is the most under-used control in the API. |
| Track what is being written about your competitors | hybrid | One query per competitor rather than a combined OR query. |
| Query an exact window, down to the minute | keyword | Both bounds accept a full timestamp, not just a date. |
| Track a slow-moving topic without drowning in it | semantic | Broad standing topics produce continuous coverage, most of it commentary. |
| Watch what is said about a named individual | hybrid | Personal names collide constantly, so add a disambiguating term — the company, the role, the sector. |
| Catch funding rounds, acquisitions and IPOs | semantic | Deal language is formulaic but varied — raises, secures, closes, lands, acquires, takes a stake. |
| Follow a topic in a specific language only | semantic | Query in English and let semantic matching bridge to the target language. |
| Monitor trial results, approvals and safety signals | semantic | Coverage here splits between company announcements, regulator statements and trade reporting, each using different vocabulary for the same event. |
| Find who reported a story first | hybrid | Deliberately not clustered — you want the individual articles and their timestamps. |
| Notice when coverage stops | hybrid | Most monitoring alerts on the appearance of coverage. |
| Produce a machine-readable daily brief | recent | A daily brief for a model is the digest recipe with the human formatting removed. |
What is deliberately missing
Only recipes this API can actually serve are listed. The competitor corpus these were drawn from contains a good many tasks built on capabilities we do not expose, and writing them up would rank for queries we then fail to satisfy — which is worse for everyone than not ranking.
The absences worth naming: there is no cross-tabulation, so you cannot ask for sentiment by outlet by week in one call and must aggregate client-side. There is no full article text, only metadata and the link, so summarisation recipes fetch from the publisher rather than from us. There is no author-level or byline analysis beyond exact-match filtering. There is no social or broadcast content at all. And there is no historical rewrite: an article is indexed as first seen, so a recipe that depends on tracking silent edits to a published piece is not implementable here.
Each of those is a real request someone has made. They are listed rather than quietly omitted so you can rule this out quickly if one of them is your requirement.
Once you have picked one
Each page here makes the case for its approach and says when that approach is wrong. The other half — what comes back field by field, how the recipe fails once it is running unattended, how to adapt it, and what it costs to schedule — is in the technical documentation at docs.unzoi.com/guides/recipes, where it sits next to the reference for every parameter these queries use.
That is also where the full REST reference, the MCP tool surface and setup for seventeen agent clients live.
The mistake that accounts for most bad results
Reaching for article search when the task wanted story grouping. It is not obvious in testing, because a single test query on a quiet day returns a sensible-looking handful of results. The failure appears on the day something happens: coverage floods, the response fills with the same event, and whatever consumes it — a model, an alert channel, a digest — degrades exactly when it mattered most.
The second most common is trusting sentiment averaged across an unfixed outlet set. Editorial stance varies more between publishers than it does between weeks, so an average over whichever outlets your query happened to reach describes the sample, not the story. Fix the outlet set first, then compare over time within it.