GET /search

Search articles.

Ranked articles with topics, entities, locations and signals. Equivalent to the `search_news` MCP tool. Credits: 1 for keyword ranking or a browse, 2 for semantic, 3 for hybrid; 1-4 with near, bbox, amount_min or amount_max, whose candidates are checked in batches of 500; a cursor page costs 1-2 to start and 1-3 after; +1-2 per entity_id; +1 when signal_percentile_min resolves a threshold; +1 per full 1000 rows of offset. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.

Ranking

mode is the parameter worth thinking about. Use hybrid when a model wrote the query — models paraphrase, and keyword ranking cannot bridge "central bank tightening" to an article that says "Fed raises rates". Use keyword when a human gave you an exact phrase, a product name or a proper noun they want matched literally. The guide goes deeper.

Omitting q entirely turns this into a recency browse — mode is reported as recent, and you can ask for it by name — which is what /top-headlines does explicitly. The same is true of the search_news tool: q is optional there too, so search_news { story_id: … } lists a story's members with no query at all.

Filters

Exact matches on indexed attributes. Adding words to q makes ranking fuzzier; adding a filter does not, and costs nothing.

Values are canonical identifiers, not free text — take them from a previous response, resolve a name with /entities, or read them off a facet count. Filters and signals explains the vocabularies. A parameter name that is not in these tables is refused with 400 and code: unknown_parameter, not ignored.

Entity ids

An id from /entities matches every spelling in its alias group, where a filter matches one. The response's resolved lists the spellings each id used, and resolving them is counted in credits_charged. Filters and signals has the rules.

Place, event classes and amounts

These filter on fields the index derives from each article's own records: the cities it mentions, the event classes its themes imply, and the amounts it mentions. Geographic search covers near, radius_km and bbox; event classes and amount bounds are in Filters and signals. A geographic or amount filter is checked against each candidate article, which can make total_relation approximate and adds to credits_charged: Exactness and cost.

Signals

Every article carries versioned industry, business-context and risk-context intensities. Range-filtering on them finds coverage with a particular character rather than a particular word.

Use signal + signal_min/signal_max for one constraint, signals for several at once, ANDed, or signal + signal_percentile_min for the top slice of whatever matched, with the value it resolved to reported as signal_threshold. See Entity and signal filtering.

Time range

Paging, shape and facets

offset pages any query. cursor pages a browse with no q, newest first: pass start, then each next_cursor, and the pages stay disjoint while new articles arrive. The two do not combine. Pagination and facets covers cursor paging, what the counts mean, and when they are approximate.

view changes the shape of a hit, not the match set. compact keeps id, language, published_at, score, source, story_id, title, url and drops the rest: the entity lists, the signal map, the tone scores. Use it when results feed a model that is deciding what to read next — the full record is one /doc/{id} away — and leave it at full when your code reads the fields.

Response

Two pairs of fields describe the answer, and they are about different things. total and total_relation say how many matched and how far to trust the number. partial and coverage say whether the index was fully read. A response can be exact and partial, or approximate and complete. A geographic or amount filter with more candidates than its scan checks makes the total approximate, and a derived filter that part of the index cannot yet apply makes the answer partial, with coverage: field_unavailable.

Article

Under view=full, the default. view=compact keeps the fields listed above.

Every hit carries event_types, the event classes its themes imply. matched_locations appears only when near or bbox filtered the request: the cities that matched, nearest first under near, each with its distance. Geographic search has the details.

Article bodies are never returned — url is where the article lives. For the long tail of an article's metadata (quotations, structured locations, amounts, alternate URLs), fetch it by id with /doc/{id}.

Example

curl -s -G "https://api.unzoi.com/search" \
  -H "x-api-key: $UNZOI_KEY" \
  --data-urlencode "q=port congestion" \
  --data-urlencode "mode=hybrid" \
  --data-urlencode "language=eng" \
  --data-urlencode "from=2026-08-01" \
  --data-urlencode "facets=source,country" \
  --data-urlencode "limit=10"

Errors

See Errors for how to back off correctly.