Skip to main content

​
Overview

The GDELT Cloud REST API provides programmatic access to GDELT event data, allowing you to query events, manage alerts, and integrate GDELT data into your applications.

Execute Queries

Run SQL queries against 30 days of GDELT events and GKG data

Manage Alerts

Create, update, and manage custom event monitoring alerts

API Keys

Generate and manage API keys for secure access

OpenAPI Spec

Full OpenAPI 3.0 specification for easy integration

​
Base URL

All API requests should be made to: 
https://gdeltcloud.com/api
All requests must use HTTPS. HTTP requests will be rejected.

​
Authentication

All API requests must use Bearer token authentication with your API key. Include your API key in the Authorization header: 
Authorization: Bearer gdelt_sk_your_api_key_here

curl https://gdeltcloud.com/api/query/execute \
  -H "Authorization: Bearer gdelt_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM gdelt_events LIMIT 10"}'
API keys are available on Scout (49/mo),∗∗Analyst∗∗(49/mo), **Analyst** (499/mo), and Professional ($1,999/mo) plans. Generate your API key →
Keep your API keys secure. Never commit them to version control or share them publicly. Use environment variables to store keys.

​
Request Format

All API requests must include:
  • Content-Type: application/json
  • Authorization: API key or session token
  • Request body: JSON-formatted data (for POST/PATCH requests)
POST /api/query/execute HTTP/1.1
Host: gdeltcloud.com
Content-Type: application/json
Authorization: Bearer gdelt_sk_your_api_key_here

{
  "sql": "SELECT * FROM gdelt_events WHERE day >= '2025-01-01' LIMIT 10"
}

​
Response Format

All API responses are JSON-formatted with a consistent structure:

​
Success Response

{
  "success": true,
  "data": [...],
  "rows": 10,
  "execution_time": 145.3
}

​
Error Response

{
  "error": "Invalid SQL syntax",
  "details": "Syntax error at line 1, column 15",
  "code": "400"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeStatusDescription
200OKRequest successful
201CreatedResource created successfully
204No ContentResource deleted successfully
400Bad RequestInvalid request parameters or body
401UnauthorizedMissing or invalid authentication
403ForbiddenInsufficient permissions or quota exceeded
404Not FoundResource not found
409ConflictResource already exists
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error occurred

​
Error Handling

Always check the HTTP status code and handle errors appropriately: 
import requests

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    data = response.json()
    print(f"Success: {data}")
    
elif response.status_code == 401:
    print("Error: Invalid API key")
    
elif response.status_code == 403:
    print("Error: Permission denied or quota exceeded")
    
elif response.status_code == 429:
    retry_after = response.headers.get('Retry-After', 60)
    print(f"Rate limited. Retry after {retry_after}s")
    
else:
    error = response.json()
    print(f"Error {response.status_code}: {error.get('error')}")

​
Rate Limiting

API requests are subject to rate limits based on your plan:
  • 100 requests/minute
  • 10,000 requests/day
  • 100,000 query units/month
Rate limit headers included in responses:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640995200

​
Pagination

For endpoints that return large result sets, use pagination parameters: 
{
  "page": 1,
  "per_page": 100,
  "total": 2547,
  "data": [...]
}
Use page and per_page query parameters to control pagination where supported.

​
Quick Start Example

Here’s a complete example to get you started: 
import requests
import os

# Configure API access
API_KEY = os.environ["GDELT_API_KEY"]
BASE_URL = "https://gdeltcloud.com/api"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Execute a query
response = requests.post(
    f"{BASE_URL}/query/execute",
    headers=headers,
    json={
        "sql": """
            SELECT 
                day, 
                actor1_name, 
                actor2_name, 
                event_code, 
                goldstein_scale
            FROM gdelt_events
            WHERE day >= '2025-01-01'
              AND action_geo_country_code = 'USA'
            ORDER BY day DESC
            LIMIT 10
        """
    }
)

if response.status_code == 200:
    data = response.json()
    print(f"Found {data['rows']} events")
    print(f"Execution time: {data['execution_time']}ms")
    
    for event in data['data']:
        print(f"{event['day']}: {event['actor1_name']} → {event['actor2_name']}")
else:
    print(f"Error: {response.json()}")

​
Available Endpoints

Queries

Execute SQL queries against GDELT data

Alerts

Create and manage event monitoring alerts

API Keys

Generate and manage API keys

​
Support & Resources

API Keys Guide

Learn how to generate and manage API keys

Authentication

Detailed authentication documentation
OpenAPI Specification: Download the full OpenAPI 3.0 spec for automated client generation.