Skip to main content

​
Get Started in Three Steps

Follow this guide to create your account, explore global events, and make your first API call.

​
Step 1: Create Your Account

1

Sign up

Visit gdeltcloud.com/auth/sign-up and create your account with email and password.
All new accounts start with free access to the Research Agent and basic features.
2

Verify your email

Check your inbox for a verification email and click the confirmation link.
3

Access the dashboard

Navigate to gdeltcloud.com/dashboard to access your account.

​
Step 2: Try the Research Agent

1

Open the Research Agent

From your dashboard, click on Research in the sidebar or navigate to the Research page.
2

Ask your first question

Try asking a question in natural language, such as:
What protests happened in France this week?
The AI will translate your question into SQL and retrieve relevant GDELT data automatically.
3

Review the results

The Research Agent will return structured data with events, actors, locations, and sentiment scores.
Results are limited to the most recent 30 days of data by default.

​
Step 3: Make Your First API Call

For programmatic access, you’ll need an API key. This requires upgrading to a paid plan.
1

Upgrade your plan

Navigate to Settings → Billing and upgrade to a paid plan that includes API access.
API keys are only available on Scout (49/mo),Analyst(49/mo), Analyst (499/mo), and Professional ($1,999/mo) plans.
2

Generate an API key

Go to Settings → API Keys and click Create New Key.
  1. Give your key a descriptive name (e.g., “Development Key”)
  2. Click Generate
  3. Copy the key immediately - it will only be shown once
Store your API key securely. It provides full access to your account and cannot be retrieved after creation.
3

Make a test request

Use your API key to execute a query:
curl -X POST https://gdeltcloud.com/api/query/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer gdelt_sk_your_api_key_here" \
  -d '{
    "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'\'' LIMIT 10"
  }'
You should receive a JSON response with event data and execution metrics.

​
Next Steps

Create Alerts

Set up custom alerts to monitor specific events and receive email notifications.

Explore the API

Learn about all available API endpoints and authentication methods.

Connect AI Agents

Use the MCP server to connect Claude, ChatGPT, or custom agents to GDELT data.

​
Common Questions

GDELT Cloud provides access to the most recent 30 days of GDELT events and GKG data, updated every 15 minutes. This includes:
  • Events table: Structured event data with actors, actions, locations, and sentiment
  • GKG table: News article themes, entities, and media coverage patterns
Data is stored in GDELT Cloud infrastructure with optimized schemas:
  • gdelt_events: Core event records (actors, event types, locations, sentiment)
  • gdelt_gkg: Global Knowledge Graph (themes, entities, tone)
  • Extracted entities: Persons, organizations, locations, themes
All tables include time-based partitioning for fast queries.
Query units measure computational cost:
  • Simple queries (filtered by date + country): ~0.1 units
  • Medium complexity (joins, aggregations): ~0.5 units
  • Complex queries (multiple tables, heavy aggregation): ~2+ units
Each plan includes a monthly allocation of query units.
Yes! All query results can be exported as:
  • JSON via API responses
  • CSV from the dashboard
  • Direct GDELT database access (Enterprise plans)
Need help? Check our API Reference for detailed documentation.