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

# API Keys

> Generate and manage API keys for programmatic access to the Developer API

## Overview

API keys provide secure programmatic access to the GDELT Cloud Developer API (`/api/v2/*` and supported `/api/v1/*` endpoints). Use v2 for new integrations: Events, Stories, Entities, summaries, geo discovery, and cursor pagination.

<Info>
  API keys require API access on the active organization. Keys are scoped to the organization that creates them.
</Info>

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

## Generating an API Key

<Steps>
  <Step title="Navigate to API Keys">
    From your dashboard, switch to the right organization, then go to **Settings -> API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **Create New Key** and give it a descriptive name (e.g. "Production", "Dev Environment").
  </Step>

  <Step title="Copy your key immediately">
    <Warning>
      Your API key is shown **only once**. Copy it now and store it securely.
    </Warning>

    Keys use the format: `gdelt_sk_<64-hex-chars>`

    Example: `gdelt_sk_a1b2c3d4...` (64 hex characters after the prefix)
  </Step>

  <Step title="Store securely">
    Use environment variables or a secrets manager. Never commit keys to version control.
  </Step>
</Steps>

## Using Your API Key

Include the key as a Bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer gdelt_sk_your_api_key_here
```

<CodeGroup>
  ```bash cURL theme={null}
  # Significant structured Events
  curl "https://gdeltcloud.com/api/v2/events?country=Lebanon&category=Battles&subcategory=Armed%20clash&has_fatalities=true&limit=10" \
    -H "Authorization: Bearer gdelt_sk_your_api_key_here"
  ```

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

  API_KEY = os.environ["GDELT_API_KEY"]
  BASE = "https://gdeltcloud.com/api/v2"
  headers = {"Authorization": f"Bearer {API_KEY}"}

  # Protests in India
  resp = requests.get(f"{BASE}/events", headers=headers,
                      params={"country": "India", "category": "Protests", "subcategory": "Peaceful protest", "limit": 10})
  data = resp.json()
  print(f"{len(data['data'])} events")

  # Entity profile
  resp = requests.get(f"{BASE}/entities", headers=headers,
                      params={"search": "NATO", "limit": 5})
  print(resp.json()["data"])
  ```

  ```javascript Node.js theme={null}
  const API_KEY = process.env.GDELT_API_KEY;
  const BASE = "https://gdeltcloud.com/api/v2";
  const headers = { "Authorization": `Bearer ${API_KEY}` };

  // Story search
  const resp = await fetch(`${BASE}/stories?continent=Asia&search=data%20center%20projects&limit=10`,
    { headers });
  const data = await resp.json();
  console.log(`${data.data.length} stories`);
  ```
</CodeGroup>

<Info>
  v1 endpoints remain supported for existing integrations. For new work, prefer [API v2](/api-reference/v2).
</Info>

## Rate Limits & Quotas

Direct REST API and direct MCP calls consume 1 Query Unit per data-tool call unless an endpoint documents otherwise. Hosted GDELT Cloud Agent UI tool calls consume 5 Query Units. Briefs are metered in Brief Units and do not consume Query Units.

When you exceed a limit, the API returns HTTP `429` with a machine-readable code:

| Scenario                 | Code             | Header                   |
| ------------------------ | ---------------- | ------------------------ |
| Per-minute RPM exceeded  | `RATE_LIMITED`   | `Retry-After: <seconds>` |
| Monthly QU quota reached | `QUOTA_EXCEEDED` | —                        |

Always check the `Retry-After` header and back off accordingly:

```python theme={null}
import time

resp = requests.get(url, headers=headers)
if resp.status_code == 429:
    retry_after = int(resp.headers.get("Retry-After", 60))
    time.sleep(retry_after)
    resp = requests.get(url, headers=headers)  # retry once
```

## Revoking a Key

Go to **Settings -> API Keys**, find the key, and click **Revoke**. Revoked keys return HTTP `401` immediately.

<Note>
  You can generate multiple API keys, such as one per environment. Each key consumes the quota of its organization. Owners and admins can review and export organization usage by feature, member, and API key.
</Note>

For company workspaces, see [Organizations and Teams](/developers/orgs-and-teams).