Skip to main content

Overview

API keys provide secure programmatic access to the GDELT Cloud Developer API — the /api/v2/* surface: Events, Stories, Entities, Situations, country context, publication activity, summaries, geo discovery, and cursor pagination.
Looking for the GDELT Project’s own APIs — DOC 2.0, GEO, Events and GKG? They need no key. The GDELT Project API guide covers their endpoints, time windows, rate limits and errors, and how this API relates to them.
API keys require API access on the active organization. Keys are scoped to the organization that creates them.
A new Free account includes 200 starter calls for the REST API and MCP server: a one-time credit that never expires, so you can create a key and make your first calls before choosing a plan. Free also keeps 50 QU a month in the web app and API Arena. When the starter calls are used, API keys, OAuth and the MCP server pause until you choose a paid plan, and a key answers 403 PROGRAMMATIC_ACCESS_DENIED with a details.pricing_url (errors). Bulk downloads and scheduled Monitors need a paid plan. Choose Builder or compare plans on Pricing.
Choose an explicit date window when its bounds matter. Core responses disclose the effective predicates in meta.query_window, separately from the available history in meta.coverage. A partial valid Event or Story range returns every safely published date and names the exact served_dates, missing_dates and window_complete state; a retryable snapshot error remains only when no partition can safely answer. See each endpoint’s parameter reference for defaults and limits.

Generating an API Key

1

Navigate to API Keys

Switch to the workspace the key should belong to, then go to gdeltcloud.com/api-keys.
2

Create a new key

Click Create New Key and give it a descriptive name (e.g. “Production”, “Dev Environment”).
3

Copy your key immediately

Your API key is shown only once. Copy it now and store it securely.
Keys use the format: gdelt_sk_<64-hex-chars>Example: gdelt_sk_a1b2c3d4... (64 hex characters after the prefix)
4

Store securely

Use environment variables or a secrets manager. Never commit keys to version control.

Using Your API Key

Include the key as a Bearer token in the Authorization header:
Before choosing filter values, use the Event category values and Event taxonomy. Story topics use story_category; on Stories, category filters the linked Events and can exclude Stories with no Event.
Keep dates and filters fixed while passing pagination.next_cursor unchanged until it is null. Then start the next date chunk without a cursor. Use the endpoint’s documented maximum number of inclusive days; a calendar month can exceed it. Oversized-window errors include coverage and a suggested valid window.
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 is a strict superset of the two v1 event routes (conflict Events and CAMEO+ domains, filtered with category): same events, stable ids, a documented cursor, and the metric fields v1 never exposed.

Metering

Every successful REST and MCP data call costs Query Units (QU) from your workspace’s allowance. Discovery calls (/api/v2/meta/*, and the local MCP catalog, schema, taxonomy and parameter-option helpers) are free. Hosted Monitoring Brief generation is temporarily unavailable across all plans; existing Brief allowances and credits remain on your account and do not draw down Query Units while generation is paused.

What a request costs

  • A successful data request costs 1 QU, whatever its limit, however many rows it returns, and whether it is a list, a summary or a search.
  • A request that fails, with any status other than 2xx, costs nothing.
  • Creating a Situation costs 5 QU, or nothing when an existing Situation is reused; the response’s quota_units says which.
  • Setting up, reading, editing, pausing and deleting Monitors is free, and so are delivery tests, the webhook demonstration and run history. A Monitor Preview and Run now cost 1 QU each. A page of a run’s matches is free within the run’s first 100 records and costs 1 QU past them. Scheduled checks never cost QU.
  • Saved queries are free to create, read, edit and delete; running one costs what its request costs.
  • Through the MCP, a data tool call costs 1 QU. Monitor, saved-query and Situation tools cost what their REST call costs.
Every /api/v2/* response carries an X-Quota-Cost header with the most the call can cost, set before the request runs: a request that fails is not charged whatever the header says. Creating a Situation is quoted at 5 QU, and its quota_units says what it charged. GET /api/v2/meta/query-units (free) lists every call’s price and reports your allowance in usage: what is left in usage.remaining, and the billing window in usage.window.start and usage.window.end. Quota admission reserves each request’s cost atomically against the current billing window. The usage report counts delivered requests, so it can lag reservations still pending. Its measurement (usage.measurement_status) is fresh, stale (with measured_at), or pending; an unknown total is null, never zero or an unlimited allowance. Keep usage.window.start and usage.window.end with any reported total when comparing billing periods.

Rate limits

Each workspace has two request limits, shared by all of its keys:
  • Per minute: a rolling 60-second count of requests, set by your plan. REST and MCP are counted separately, and refused requests count too.
  • At once: a cap on requests still running, shared by REST and MCP.
Over either limit the API answers 429 RATE_LIMITED, and Retry-After gives the seconds to wait. details.reason says which limit: requests_per_minute, with your limit in details.rpm_limit and the X-RateLimit-Limit header, or concurrency, with your limit in details.concurrency_limit and the X-Concurrency-Limit header. Successful responses carry no remaining-requests header, so keep parallel requests few and back off when a 429 arrives. 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.

Revoking a Key

Go to gdeltcloud.com/api-keys, find the key, and click Revoke. Revoked keys return HTTP 401 immediately.
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.
Keys belong to the workspace that created them, and a request is metered against that workspace.