Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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 your GDELT Cloud account.
V2 Event and Story list/summary calls default to confidence_profile=precise for clean, analyst-ready results. Add confidence_profile=loose only when exhaustive/raw retrieval is required.

​
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

# Significant structured Events
curl "https://gdeltcloud.com/api/v2/events?country=Lebanon&event_family=conflict&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

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.