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 Research Agent will find relevant media event stories and present them with article links, entity context, and sentiment analysis.
3

Review the results

Results include media event clusters (stories), the articles that make up each story, linked entities, and CAMEO event metrics like Goldstein scale and tone scores.
Data starts from January 2025 and is growing over time as historical data is gradually added. New data is updated hourly.

​
Step 3: Make Your First API Call

For programmatic access, you’ll need an API key on the Analyst or Professional plan.
1

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 is shown only once
Store your API key securely. Never commit it to version control.
2

Make your first request

Fetch today’s top media event clusters:
curl "https://gdeltcloud.com/api/v1/media-events?days=1&limit=5&detail=summary" \
  -H "Authorization: Bearer gdelt_sk_your_api_key_here"
You should receive a JSON response with clusters, filters, and metadata fields.

​
Next Steps

Explore the API

Learn about all available API endpoints, filters, and response detail levels.

Connect AI Agents

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

Research Agent

Learn how the AI-powered Research Agent helps you explore global events.

​
Common Questions

GDELT Cloud provides access to GDELT event data starting from January 2025, with new data updated hourly. Historical coverage is being expanded over time. The data includes:
  • Media Events: News articles clustered into stories with sentiment, actors, and locations
  • Entities: People and organizations linked across stories via Wikipedia (GEG entities)
  • Domains: News source profiles with coverage patterns and top entities
GDELT Cloud organizes data in layers:
  • Articles: Individual news articles from thousands of global sources
  • Events: Structured CAMEO-coded events extracted from articles (who did what to whom, where)
  • Media Events: Clusters of related articles forming a single “story” — the primary unit of analysis
  • Entities: People and organizations identified across stories, linked to Wikipedia for disambiguation
API responses support progressive disclosure via the detail parameter:
  • summary: Compact headline cards (~120 tokens/cluster) — great for scanning
  • standard: Adds article links and entity details (~500 tokens/cluster)
  • full: Complete data with per-article metrics (~1,000 tokens/cluster)
Start with summary for discovery, then zoom into specific stories.
Yes! All query results are returned as JSON via API responses. The Research Agent also displays results in structured formats with source links.
Need help? Check our API Reference for detailed documentation.