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.
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.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
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 theAuthorization header:
story_category; on Stories,
category filters the linked Events and can exclude Stories with no Event.
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 asearch. - 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_unitssays 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.
/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.
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 HTTP401 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.

