Skip to content
unzoi docs
Search and navigation
Start here
REST API
MCP
Limits and plans
Agent clients
SDKs
Guides

Recipes / Find coverage with a particular tone

Find coverage with a particular tone

/search in hybrid mode. This page is the operational half — what comes back, how it breaks, and what running it for real takes.

The request

GET /search
  ?q=<subject>
  &mode=hybrid
  &from=<now - 7d>

# each result carries a tone score; filter client-side
results.filter(a => a.tone > 2)

As a call you can paste:

curl -s -G "https://api.unzoi.com/search" \
  -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "q=<subject>" \
  --data-urlencode "mode=hybrid" \
  --data-urlencode "from=<now - 7d>" \
  --data-urlencode "results.filter(a => a.tone > 2)"

For an agent rather than a script, the same query is the search_news MCP tool with these as its arguments.

Parameters used here

What comes back

Articles with a numeric tone value. Strongly positive and strongly negative both sit far from zero; most coverage clusters near it, so a threshold of roughly ±2 separates the genuinely charged pieces from the neutral bulk.

Field by field: the /search response reference.

How this goes wrong

Averaging tone across an outlet set you did not choose. Editorial stance moves tone more than events do, so the average describes which publishers your query reached.

Adapting it

The same client-side filter works for the negative tail, which is the more common requirement — reputational monitoring wants tone below a threshold rather than above it. For comparison across subjects, normalise: tone distributions differ by topic, so a score that is unusually positive for disaster coverage is unremarkable for product launches. Compute the distribution for your subject over a baseline period and filter on percentile rather than on the raw value.

Running it for real

Retrieve more than you intend to keep, because filtering happens after retrieval and a tone threshold can discard most of a page. Requesting a hundred and keeping the top decile costs one call; requesting ten and paging until you have enough costs several. Cache the tone distribution per subject and recompute it weekly rather than per query — it moves slowly, and recomputing it on every run doubles your credit spend for no gain.

Why this approach

The case for these parameters over the obvious alternatives — and when this recipe is the wrong tool entirely — is on the recipe's page on unzoi.com. It is kept there rather than repeated here, so the argument and the operations cannot drift apart.