Skip to main content

​
Overview

API keys provide secure programmatic access to the GDELT Cloud Developer API (/api/v1/*). Use them in your scripts, applications, and integrations to query media events, entity data, and domain profiles.
API keys are available on Analyst and Professional plans only.

​
Plan Limits

PlanMonthly QURPMAPI Access
Free100—✗
Scout1,000—✗
Analyst10,00030 req/min✓
ProfessionalUnlimited120 req/min✓
QU = Query Units (1 QU per request). RPM = per-minute rate limit.

​
Generating an API Key

1

Navigate to API Keys

From your dashboard, 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

# Today's top media events
curl "https://gdeltcloud.com/api/v1/media-events?days=1&limit=10" \
  -H "Authorization: Bearer gdelt_sk_your_api_key_here"

​
Rate Limits & Quotas

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 (e.g. one per environment). Each key counts against the same account quota.