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
GDELT Cloud supports multiple authentication methods depending on your use case:| Method | Use Case | Where |
|---|---|---|
| Session Auth | Web dashboard, interactive use | Browser |
| API Keys | Programmatic access, automation | REST API, MCP Server |
Session Authentication
Session authentication is used when accessing GDELT Cloud through the web dashboard.How It Works
Login
Navigate to gdeltcloud.com/auth/sign-in and enter your credentials.
Session created
Upon successful login, a secure session cookie is created and stored in your browser.
Sessions are powered by Supabase Auth and include automatic token refresh for seamless long-term use.
Session Security
- Sessions expire after 7 days of inactivity
- HTTPS-only cookies prevent interception
- CSRF protection on all state-changing operations
- Optional two-factor authentication (coming soon)
API Key Authentication
API keys provide programmatic access to the Developer API. Use/api/v2/* for new integrations; /api/v1/* remains supported for existing direct API users.
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.
Key Format
gdelt_sk_a1b2c3d4e5f6... (64 hex chars after the prefix)
Usage
Include the key as a Bearer token in every request:Authentication Errors
| HTTP | Code | Meaning |
|---|---|---|
| 401 | MISSING_API_KEY | No Authorization header |
| 401 | INVALID_API_KEY | Wrong format or revoked key |
| 403 | API_ACCESS_DENIED | API access is not enabled for the key |
| 429 | RATE_LIMITED | Request rate limit exceeded |
| 429 | QUOTA_EXCEEDED | Usage limit reached |
Generate and manage API keys in Dashboard → Settings → API Keys. See API Keys for full details.