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

Quickstart

A key, a first request, and a first tool call.

1. Get a key

Sign in at console.unzoi.com and create a key. Signing up and signing in are the same magic-link action, and the free tier needs no card.

Keys look like nai_ followed by 48 hex characters. The console shows a key once, at creation — only its hash is stored, so a lost key is rotated rather than recovered.

2. Your first request

curl -s "https://api.unzoi.com/search?q=semiconductor+export+controls&limit=3" \
  -H "x-api-key: $UNZOI_KEY"

What comes back:

{
  "total": 41,
  "total_relation": "exact",
  "offset": 0,
  "limit": 3,
  "has_more": true,
  "mode": "keyword",
  "partial": false,
  "coverage": "complete",
  "results": [
    {
      "id": "20260826073000-a1b2c3",
      "title": "New export controls tighten chip supply",
      "url": "https://example.com/chips",
      "source": "reuters.com",
      "language": "eng",
      "published_at": "20260826073000",
      "story_id": "s-9f2c",
      "topics": ["ECON_TRADE", "TECH_SEMICONDUCTOR"],
      "organizations": ["asml"],
      "countries": ["NL", "CN"]
    }
  ],
  "history_days": 30,
  "from_clamped": false,
  "attribution": "Data derived from the GDELT Project (https://www.gdeltproject.org/)."
}

Four fields there are about the answer rather than about the news. history_days is how far back your plan may query, and from_clamped says whether this request hit that boundary — Archive depth explains both. partial and coverage say whether the whole index was read; when they are anything but false and complete, a short list is not the answer — Reading completeness.

3. Collapse the duplicates

That search returned 41 articles, but not 41 events — a wire story runs across many outlets. Ask for stories instead: 

curl -s "https://api.unzoi.com/stories?q=semiconductor+export+controls&limit=3" \
  -H "x-api-key: $UNZOI_KEY"
{
  "total": 6,
  "partial": false,
  "coverage": "complete",
  "stories": [
    {
      "story_id": "s-9f2c",
      "count": 23,
      "outlets": 19,
      "title": "New export controls tighten chip supply",
      "url": "https://example.com/chips",
      "sources": ["reuters.com", "bbc.co.uk", "ft.com"]
    }
  ]
}

Six events rather than 41 articles, each carrying how many outlets ran it. Fetch /stories/{story_id} to expand one into the whole event — every outlet, when it was first and last seen, what it is about, its newest articles: 

curl -s "https://api.unzoi.com/stories/s-9f2c?limit=5" -H "x-api-key: $UNZOI_KEY"

4. Connect an agent

The same index is an MCP server at https://api.unzoi.com/mcp. In Claude Code, one command: 

claude mcp add --transport http unzoi https://api.unzoi.com/mcp \
  --header "x-api-key: $UNZOI_KEY"

Then ask something that needs current reporting, and watch the tool call in the transcript.

For every other client — Claude Desktop, ChatGPT, Cursor, Windsurf, VS Code, Zed, Cline, Continue, Goose, LangChain, LlamaIndex, n8n, Bedrock AgentCore — see Agent clients. Each page carries the config for that client and the mistake people actually make with it.

5. Know your budget

curl -s https://api.unzoi.com/account -H "x-api-key: $UNZOI_KEY"

Plan, credits a minute, the monthly credit allocation and how much of it is used, whether the key stops at its allocation or bills overage, and the archive depth — free to ask. Every response also carries the same figures as headers, and says what it cost in x-credits-charged. To price a call before running it, add estimate=true; nothing runs and nothing is charged. Credits and overage has what each call costs.

Where next