How to query the GDELT API without drowning the agent

A research agent is asked for "the port strike." It calls the GDELT DOC API with that phrase and nothing else. The default search covers the last three months and answers in HTML. The next tool call, two seconds later, asks for tone. The API returns 429 and tells the client to slow down. The model retries immediately. The agent now has a pile of markup, no articles in context, and a rate limit it keeps refreshing.

This post is how to shape one GDELT DOC 2.0 query so the result fits in an agent, and what to do with the 429.

The defaults return a browser page

The DOC 2.0 debut documents the endpoint https://api.gdeltproject.org/api/v2/doc/doc. The examples are query strings. There is no API key parameter on them. You can call it without a credential. That is unusual, and it is why people drop the URL straight into an agent.

TIMESPAN defaults to the last three months. FORMAT defaults to HTML, meant for a browser or an iframe. MAXRECORDS applies to article list and image collage modes. The default cap is 75 articles. You can raise it to 250. Other modes ignore MAXRECORDS. Sort defaults to relevance, not "newest first."

An agent that omits format=json receives HTML. An agent that omits timespan searches a quarter of global news. An agent that raises maxrecords to 250 because "more is better" pulls the maximum article list into the model. None of those are auth bugs. They are query bugs. ScrapeGraph for research agents is a different fetch, of one page you already chose. GDELT is the search that decides which pages exist. Do not paste 250 of them into the prompt and call it reading.

A query that names the window

Put the keyword in query. Put a short window in timespan. The debut post allows minutes (15min is the minimum), hours (6h), days, weeks, and months. Put mode=artlist when you want articles. Put format=json. Put maxrecords well under 250. Put sort=datedesc when the user asked for the latest, because relevance will not do that.

This is a complete query for a six-hour window and 25 articles:

https://api.gdeltproject.org/api/v2/doc/doc?query=%22port%20strike%22&mode=artlist&format=json&maxrecords=25&timespan=6h&sort=datedesc

ArtList is the mode that returns the article list. TimelineVol is the mode that returns volume over time and is the better call when the question is "did coverage spike," because you do not need 25 headlines to see a spike. TimelineVol ignores maxrecords. Pick the mode that matches the question before you pick the count.

STARTDATETIME and ENDDATETIME use YYYYMMDDHHMMSS and must fall inside the last three months. If you need 2024, this API is the wrong tool. Say that in the answer instead of widening timespan until the payload explodes.

Operators live inside query, not as sibling URL parameters. GDELT's post is explicit that the operators are part of the query value. A client that splits sourcecountry:us into its own parameter will not filter the way the author expected.

The 429 wants five seconds, and a retry loop will not get them

Callers that hit the DOC API too quickly receive HTTP 429. The response tells you to limit requests to one every 5 seconds. That gap is the pacing rule. An agent loop that issues a volume query and an article query back to back will trip it. An agent that treats 429 as "try again now" will stay there.

Wait at least five seconds. Then send one follow-up, not three. API observability for this provider is mostly a count of 429s and a count of article-list calls. A healthy research hour is a handful of queries. A broken one is hundreds of 429s and an empty summary.

Cache the JSON for that exact query string. The same question from a second user should reuse the cache inside the five-second world, not hit GDELT again. HTML responses should be treated as a bug in the query, not as text to summarize. If format was omitted, fix the query. Do not ask the model to scrape a visualization page.

Search does not list a GDELT bundle

swy search gdelt returns no provider. The public DOC URL is not a bundle you enable with swy add. Business and Enterprise can bring your own provider if you need the call inside the same allowlist as everything else. Until that exists, the agent should call this URL with the parameters above, from code you review, with the five-second wait in that code.

Do not invent a method id. If a later swy search gdelt prints a name, use that name with swy get and only then swy list methods. A catalog page for the project is at the GDELT listing. The listing is not a promise that swy search returns a bundle today.

One artlist call, 25 records, six hours, JSON. Wait five seconds before any second call. If the question is a spike, use mode=TimelineVol and skip the article dump.

Related reading

• Log every API call an agent makes. A 429 is a call worth counting even when the provider has no key.
• Policy as code for agent calls. Where a brought-your-own GDELT method would grow a maxrecords ceiling.
• API governance tools for AI agents. How an undocumented fetch sits next to an allowlist.
• Best API observability tools for agent traffic. What to use when 429 rate is the signal you care about.

FAQ

Does the GDELT DOC API require a key?

The DOC 2.0 examples are plain URLs with query, mode, and timespan. No key parameter is part of those examples. You still have to pace calls. No key does not mean no limit.

What happens if I omit format and timespan?

You get HTML, and the search covers the last three months. Article list mode then returns up to 75 records unless you set maxrecords, which tops out at 250. Set format=json, a short timespan, and a small maxrecords for an agent.

Can I pull a year of coverage?

STARTDATETIME and ENDDATETIME have to sit inside the last three months. A longer history is outside this endpoint. Narrow the question or use a different archive.

Is GDELT in the Swytchcode registry?

swy search gdelt does not return a provider. You can still call the public URL from your own code. Bringing it in as your own provider is a Business and Enterprise path, and it starts only after search shows a name you can swy get.