> ## 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 — the `/api/v2/*` surface: 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>

Event and story list endpoints default to a rolling **7-day** window, not to all of history; other families differ and the declared default is on each parameter in the [API reference](/api-reference). Narrow with a date window and any of the filters in the [parameter reference](/reference/parameters), whose legal values are in the [value reference](/reference/enums).

## Generating an API Key

<Steps>
  <Step title="Navigate to API Keys">
    Switch to the workspace the key should belong to, then go to [gdeltcloud.com/api-keys](https://gdeltcloud.com/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 is retired.** Every `/api/v1/*` path returns `410 Gone` naming its v2 replacement — in the
  error message, in `details.replacement`, and in an RFC 8594 `Link` header — so a client that still
  calls one gets told where to go rather than a silent failure. `/api/v2/events?family=conflict` and
  `?family=cameoplus` are strict supersets of the two event routes: same events, stable ids, a
  documented cursor, and the metric fields v1 never exposed.
</Info>

## Metering

Every REST and MCP data call consumes Query Units against your account's allowance. Discovery calls
(`/api/v2/meta/*`, and the MCP `_tool_list` / `_tool_get` tools) are not metered. Briefs meter
separately and never draw down Query Units.

Responses carry your current usage in headers, and the API tells you when a limit binds rather than
degrading quietly — every metering and entitlement error, with its `code` and what to do about it, is
in the [error reference](/reference/errors).

## Revoking a Key

Go to [gdeltcloud.com/api-keys](https://gdeltcloud.com/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>

Keys belong to the workspace that created them, and a request is metered against that workspace.