changedInput schema / properties / maxRecords / description
Previous value: -"Maximum number of clips to return (1–3000). 3000 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 3000 must be split into narrower startDatetime/endDatetime windows instead."New value: +"Maximum number of clips to fetch (1–3000); the response carries as many of them as fit its 48,000-byte budget. 3000 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 3000 must be split into narrower startDatetime/endDatetime windows instead."
changedOutput schema / properties / continuationWindows / description
Previous value: -"The queried window halved, to re-run this query against one pair at a time when maxRecords is at its 3000 ceiling. The halves overlap by one second so no clip falls through the seam; a clip aired on that second can come back in both, so de-duplicate by archiveUrl. Absent unless the ceiling was reached with a window that is both known and wide enough to divide."New value: +"Windows to re-run this query against, one at a time, when more clips are out of reach of this response. For a response cut to its budget under dateDesc or dateAsc: one window resuming from the last returned clip, reaching back to the second it aired, so clips from that second come back again — de-duplicate by archiveUrl — or, when resuming there cannot reach a new clip, one window skipping past that second. Otherwise — maxRecords at its 3000 ceiling, or a relevance cut — the queried window split in two, on a clock hour when one falls inside it; the halves share no second. Absent when no window is known, or none would reach further."
changedOutput schema / properties / error / properties / data / properties / reason / description
Previous value: -"Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of startDatetime / endDatetime was supplied, one of them is not a real UTC calendar timestamp, or startDatetime is not earlier than endDatetime. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request for its one-request-per-five-seconds limit, or too many requests were already queued for this one to start in time. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."
changedOutput schema / properties / error / properties / data / properties / reason / examples
Previous value: -[
- "no_clips",
- "invalid_date_range",
- "invalid_query",
- "gdelt_rate_limited",
- "gdelt_unavailable"
-]New value: +[
+ "invalid_date_range",
+ "invalid_query",
+ "gdelt_rate_limited",
+ "gdelt_unavailable"
+]
changedOutput schema / properties / notice / description
Previous value: -"Disclosure that the maxRecords cap was reached and more clips may exist, naming the route to them — a higher maxRecords below the 3000 ceiling, or a narrower date window at it. Absent when the full result set fit under the cap."New value: +"Guidance on an incomplete or empty result. When no clips matched, the resolved timespan window and how to target the 2009–October 2024 archive or verify station IDs. When GDELT returned clips aired outside the requested window (it answers whole clock hours), how many were dropped. When the response was cut to its 48,000-byte budget, how many clips it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more clips may exist — a higher maxRecords below the 3000 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget."
addedOutput schema / properties / withheldCount
Added value: +{
+ "description": "In-window clips GDELT returned that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting clips dropped for falling outside the window. Absent when every in-window clip fit.",
+ "type": "number"
+}