> ## 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.

# Quickstart

> Get started with GDELT Cloud v2, REST API, and MCP

## Get Started in Three Steps

### Step 1: Create Your Account

<Steps>
  <Step title="Sign up">
    Visit [gdeltcloud.com/auth/sign-up](https://gdeltcloud.com/auth/sign-up) and create your account.
  </Step>

  <Step title="Verify your email">
    Confirm your email and open the dashboard.
  </Step>

  <Step title="Explore the app">
    Start with the dashboard, Events, Stories, and entity pages.
  </Step>
</Steps>

### Step 2: Understand Common Questions

These questions map to the v2 product surface:

<CodeGroup>
  ```text Protests theme={null}
  Show protests in India by day over the past month.
  ```

  ```text Infrastructure theme={null}
  Find new data center projects in Asia and show the linked Events.
  ```

  ```text Conflict theme={null}
  Show fatal conflict Events in Lebanon this week with citations.
  ```

  ```text Market Context theme={null}
  Assess sanctions and market implications from the latest shipping disruption signals.
  ```
</CodeGroup>

For analysis workflows, anchor on GDELT Cloud structured Events and Stories, then use macro-finance, prediction-market, and web-research tools when they add context.

### Step 3: Make Your First API Call

For programmatic access, generate an API key with API access.

Event, Story, and Entity list calls default to the exact past 24 hours. Narrow with developer-facing filters such as `category`, `subcategory`, `country`, `region`, `continent`, date windows up to 30 days, `sort`, and pagination. For Conflict Events, use ACLED-style event types such as `Battles`, `Protests`, or `Explosions/Remote violence` as `category`, then use sub-event types such as `Armed clash` or `Peaceful protest` as `subcategory`. `event_family` is deprecated in favor of `category`.

<CodeGroup>
  ```bash Events theme={null}
  curl "https://gdeltcloud.com/api/v2/events?country=Lebanon&category=Explosions%2FRemote%20violence&subcategory=Air%2Fdrone%20strike&has_fatalities=true&date_start=2026-04-11&date_end=2026-04-17&sort=significance&limit=5" \
    -H "Authorization: Bearer gdelt_sk_your_api_key_here"
  ```

  ```bash Stories theme={null}
  curl "https://gdeltcloud.com/api/v2/stories?continent=Asia&search=new%20data%20center%20projects&article_count_min=1&date_start=2026-04-11&date_end=2026-04-17&sort=significance&limit=5" \
    -H "Authorization: Bearer gdelt_sk_your_api_key_here"
  ```

  ```python Python theme={null}
  import os
  import requests

  headers = {"Authorization": f"Bearer {os.environ['GDELT_API_KEY']}"}
  resp = requests.get(
      "https://gdeltcloud.com/api/v2/events",
      headers=headers,
      params={
          "category": "Protests",
          "subcategory": "Peaceful protest",
          "country": "India",
          "date_start": "2026-04-11",
          "date_end": "2026-04-17",
          "sort": "significance",
          "limit": 5,
      },
  )
  data = resp.json()
  for event in data["data"]:
      print(event["id"], event["title"], event["geo"]["country"])
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch(
    "https://gdeltcloud.com/api/v2/stories?continent=Asia&search=data%20center%20projects&limit=5",
    { headers: { Authorization: `Bearer ${process.env.GDELT_API_KEY}` } }
  );
  const data = await resp.json();
  console.log(data.data.map((story) => [story.id, story.title, story.url]));
  ```
</CodeGroup>

## What Data Is Available?

GDELT Cloud provides generated products built from the upstream GDELT Project article stream:

* **Events**: structured Conflict and CAMEO+ records.
* **Stories**: generated clusters of related articles with top article evidence.
* **Entities**: people and organizations linked to Stories and Events.
* **Summaries**: dashboard-ready rollups by date, geography, category, and subcategory.
* **Geo discovery**: country-scoped `admin1` values for state/province drilldown.

Data currently starts from **January 2025**, updates hourly, and is expanding historically over time.

## Next Steps

<CardGroup cols={2}>
  <Card title="API v2" icon="code" href="/api-reference/v2">
    Recommended REST API for Events, Stories, Entities, summaries, and geo discovery.
  </Card>

  <Card title="MCP Server" icon="plug" href="/mcp/introduction">
    Connect through Progressive Discovery.
  </Card>

  <Card title="API Keys" icon="key" href="/developers/api-keys">
    Generate and manage API keys.
  </Card>
</CardGroup>