Skip to main content

​
Overview

API keys provide secure programmatic access to the GDELT Cloud Developer API (/api/v2/* and supported /api/v1/* endpoints). Use v2 for new integrations: Events, Stories, Entities, summaries, geo discovery, and cursor pagination.
API keys require API access on the active organization. Keys are scoped to the organization that creates them.
V2 Event, Story, and Entity list calls default to the exact past 24 hours. Narrow with developer-facing filters such as category, subcategory, country, region, continent, date windows up to 30 days, sort, and pagination.

​
Generating an API Key

1

Navigate to API Keys

From your dashboard, switch to the right organization, then go to Settings -> API Keys.
2

Create a new key

Click Create New Key and give it a descriptive name (e.g. “Production”, “Dev Environment”).
3

Copy your key immediately

Your API key is shown only once. Copy it now and store it securely.
Keys use the format: gdelt_sk_<64-hex-chars>Example: gdelt_sk_a1b2c3d4... (64 hex characters after the prefix)
4

Store securely

Use environment variables or a secrets manager. Never commit keys to version control.

​
Using Your API Key

Include the key as a Bearer token in the Authorization header: 
Authorization: Bearer gdelt_sk_your_api_key_here

# Significant structured Events
curl "https://gdeltcloud.com/api/v2/events?country=Lebanon&category=Battles&subcategory=Armed%20clash&has_fatalities=true&limit=10" \
  -H "Authorization: Bearer gdelt_sk_your_api_key_here"
v1 endpoints remain supported for existing integrations. For new work, prefer API v2.

​
Rate Limits & Quotas

Direct REST API and direct MCP calls consume 1 Query Unit per data-tool call unless an endpoint documents otherwise. Hosted GDELT Cloud Agent UI tool calls consume 5 Query Units. Briefs are metered in Brief Units and do not consume Query Units. When you exceed a limit, the API returns HTTP 429 with a machine-readable code:
ScenarioCodeHeader
Per-minute RPM exceededRATE_LIMITEDRetry-After: <seconds>
Monthly QU quota reachedQUOTA_EXCEEDED—
Always check the Retry-After header and back off accordingly: 
import time

resp = requests.get(url, headers=headers)
if resp.status_code == 429:
    retry_after = int(resp.headers.get("Retry-After", 60))
    time.sleep(retry_after)
    resp = requests.get(url, headers=headers)  # retry once

​
Revoking a Key

Go to Settings -> API Keys, find the key, and click Revoke. Revoked keys return HTTP 401 immediately.
You can generate multiple API keys, such as one per environment. Each key consumes the quota of its organization. Owners and admins can review and export organization usage by feature, member, and API key.
For company workspaces, see Organizations and Teams.