Skip to content
unzoi docs

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",
  "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/)."
}

Two fields there are about your plan 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.

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,
  "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. Pass a story_id back as a filter to expand one cluster into its articles.

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, per-minute rate, monthly quota, month-to-date usage, whether the key stops at its quota or bills overage, and the archive depth. Every response also carries the same figures as headers, so you rarely need to ask twice. Limits and plans covers all three.

Where next