# Unzoi

Search a global news index: keyword, semantic and hybrid ranking over articles
from outlets worldwide, with story clustering that collapses one event across
every outlet that covered it.

## Machine-readable

- OpenAPI 3.1: https://api.unzoi.com/openapi.json
- MCP tool schemas: https://api.unzoi.com/mcp/tools.json
- MCP endpoint: https://api.unzoi.com/mcp

## Guides

- https://api.unzoi.com/docs/search-recipes.md - worked examples, and which tool to reach for

## Auth

Send `x-api-key: nai_...`, or `Authorization: Bearer nai_...` - both work, on
REST and on MCP. A key is required: every endpoint except this page and the
schemas above answers 401 without one. Keys are issued at
https://console.unzoi.com.

## MCP

Streamable HTTP at https://api.unzoi.com/mcp. The protocol version is negotiated - offer
yours and the server answers with what it picked. The endpoint is stateless, so
no session has to be kept alive, and any replica can answer any request.

## Limits

Three of them, and all three are visible before you hit them.

A PER-MINUTE rate: `x-ratelimit-limit` / `-remaining` / `-reset` on every
response, and `retry-after` on a 429. Read them rather than backing off blind.

A MONTHLY quota: `x-quota-limit` / `-used` / `-remaining` / `-reset`. A key that
hard-caps stops at its quota; one that does not bills overage instead.

An ARCHIVE DEPTH: how far back the plan may query, in `x-plan-history-days`
(absent = the full archive). A `from` older than that is pulled forward rather
than refused, and the response says so with `from_clamped: true` - so fewer
results than you expected is a plan boundary you can see, not coverage you have
to guess at. `GET /account`, and the `account_status` tool, report all three.

## Cost

Every request counts against the monthly allowance, whichever transport it
arrives on. Prefer /stories over /search when results go into a context window:
one event returns once, with the outlets that covered it, instead of forty times.

## Tools

- `search_news` - Search the news index.
- `list_stories` - Search and collapse results into deduplicated stories (one real event across many outlets).
- `top_headlines` - Most-recent articles, optionally filtered by indexed article metadata and time range..
- `get_article` - Fetch a single article's rich metadata by id, including names, structured locations and dates, quotations, amounts, related media, links, and alternate URLs..
- `find_related` - Find articles semantically similar to a given article id (More-Like-This).
- `account_status` - Report this session's account: plan, per-minute rate limit, monthly quota and how much of it is used, whether the key stops at its quota or bills overage, how far back the plan may query (history_days; null = the full archive), calls made this session, and whether metered billing is active.

FREE: this tool is not billed against your quota in any way you would notice, and it is how to plan a time range instead of discovering the archive boundary by getting fewer results than you expected..

## Attribution

Data derived from the GDELT Project (https://www.gdeltproject.org/).