Previous value: -"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]). Alternatively use station:, network:, or quoted market: selectors in query. A selector is required; use gdelt_list_tv_stations for station IDs, networks, markets, and monitoring dates."New value: +"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]) — the stationId values gdelt_list_tv_stations returns, not display labels such as \"FOX News\". Alternatively use station:, network:, or quoted market: selectors in query. A selector is required; use gdelt_list_tv_stations for networks, markets, and monitoring dates."

Previous value: -"Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV coverage varies by station; check monitoring dates with gdelt_list_tv_stations."New value: +"Relative window counting back from now (a number and unit such as d, m, or y). Now is past the end of most stations' monitoring, so for archived periods set startDatetime/endDatetime inside a station's range from gdelt_list_tv_stations. Ignored when startDatetime/endDatetime are set."

Previous 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."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`: A stations entry is not a station ID, GDELT rejected the query — no station was selected, or the query string is malformed — or the TV timespan 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."

Previous value: -"Guidance on an incomplete or empty result. When no clips matched, the resolved timespan window and how to check station monitoring dates and choose an explicit window. When GDELT returned clips aired outside the requested window, how many were dropped. When the maxRecords cap was reached, raise maxRecords below the 3000 ceiling or narrow the date window at it. When a returned clip has no station ID, why: GDELT returned it without a station label, or its station catalog did not load or has no entry for the named label — with how to look the ID up. Absent when a non-empty result set is below the cap, no clip was dropped as out of window, and every clip carries its station ID."New value: +"Guidance on an incomplete or empty result. When no clips matched, or every returned clip aired outside the requested window: the resolved timespan window; for each selected station whose monitoring range the window misses, that range and how to search inside it; and how to check station monitoring dates and choose an explicit window. When GDELT returned clips aired outside the requested window, how many were dropped. When the maxRecords cap was reached, raise maxRecords below the 3000 ceiling or narrow the date window at it. When a returned clip has no station ID, why: GDELT returned it without a station label, or its station catalog did not load or has no entry for the named label — with how to look the ID up. Absent when a non-empty result set is below the cap, no clip was dropped as out of window, and every clip carries its station ID."

Added value: +{
+  "additionalProperties": false,
+  "description": "Present only when the refetch of this exact request was refused, failed, or came back empty, and the response is GDELT's stored answer from fetchedAt instead. It holds nothing published after fetchedAt; a relative timespan covers the window ending at fetchedAt, not now. Absent on a live answer.",
+  "properties": {
+    "ageSeconds": {
+      "description": "Age of the stored answer when served, in whole seconds.",
+      "type": "number"
+    },
+    "fetchedAt": {
+      "description": "ISO 8601 time GDELT returned the stored answer.",
+      "type": "string"
+    },
+    "reason": {
+      "description": "Why the refetch was not used: GDELT rate-limited it, did not answer with data, or answered empty — which GDELT also does under load.",
+      "enum": [
+        "gdelt_rate_limited",
+        "gdelt_unavailable",
+        "gdelt_empty"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "fetchedAt",
+    "ageSeconds",
+    "reason"
+  ],
+  "type": "object"
+}

Previous value: -"Maximum number of clips to fetch (1–3000; a value up to 30000 runs at 3000, and the response says so in limitClamp). 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."New value: +"Maximum number of clips to fetch. Defaults to 50; values above 3000 run at 3000 with a limitClamp disclosure unless clamping is disabled. Every fetched in-window record is returned. 3000 is GDELT's hard per-call ceiling, with no cursor; split a query that fills it into narrower startDatetime/endDatetime windows."

Removed value: -30000

Added value: +1

Previous value: -"integer"New value: +"number"

Previous value: -"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]). The GDELT TV API requires at least one station — supply it here, or embed a station: selector directly in query. Omitting both is rejected; it does not fall back to all stations. Use gdelt_list_tv_stations to see valid IDs."New value: +"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]). Alternatively use station:, network:, or quoted market: selectors in query. A selector is required; use gdelt_list_tv_stations for station IDs, networks, markets, and monitoring dates."

Previous value: -"Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV data spans 2009–October 2024."New value: +"Time window, e.g. \"1m\", \"6m\". Ignored when startDatetime/endDatetime are set. TV coverage varies by station; check monitoring dates with gdelt_list_tv_stations."

Previous 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."New value: +"Windows to re-run this query against when maxRecords reaches its 3000 ceiling: the queried window split in two on a clock hour, with no shared second. Absent when no window is known or narrowing cannot reach further clips."

Previous 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. When a returned clip has no station ID, why: GDELT returned it without a station label, or its station catalog did not load or has no entry for the named label — with how to look the ID up. Absent when a non-empty result set fit under both the cap and the budget, no clip was dropped as out of window, and every clip carries its station ID."New value: +"Guidance on an incomplete or empty result. When no clips matched, the resolved timespan window and how to check station monitoring dates and choose an explicit window. When GDELT returned clips aired outside the requested window, how many were dropped. When the maxRecords cap was reached, raise maxRecords below the 3000 ceiling or narrow the date window at it. When a returned clip has no station ID, why: GDELT returned it without a station label, or its station catalog did not load or has no entry for the named label — with how to look the ID up. Absent when a non-empty result set is below the cap, no clip was dropped as out of window, and every clip carries its station ID."

Removed 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"
-}

Previous 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."New value: +"Maximum number of clips to fetch (1–3000; a value up to 30000 runs at 3000, and the response says so in limitClamp). 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."

Previous value: -3000New value: +30000

Previous value: -"Station ID (e.g. \"CNN\")."New value: +"Station ID — the value the stations input and the station: operator take (e.g. \"FOXNEWS\"). Absent when GDELT's label for the station could not be resolved to an ID; notice says why."

Added value: +{
+  "description": "GDELT's display label for the station (e.g. \"FOX News\"). Empty when GDELT returned the clip without one; notice says so.",
+  "type": "string"
+}

Previous value: -[
-  "show",
-  "station",
-  "date",
-  "snippet",
-  "archiveUrl"
-]New value: +[
+  "show",
+  "stationName",
+  "date",
+  "snippet",
+  "archiveUrl"
+]

Added value: +{
+  "additionalProperties": false,
+  "description": "Present only when the requested count exceeded the per-call cap: the call ran exactly as a call at the cap, and every count, notice, and continuation in this response reflects the applied value.",
+  "properties": {
+    "applied": {
+      "description": "The per-call cap the call ran with instead.",
+      "type": "number"
+    },
+    "parameter": {
+      "description": "The count input that was clamped.",
+      "enum": [
+        "maxRecords",
+        "limit"
+      ],
+      "type": "string"
+    },
+    "requested": {
+      "description": "The value the call asked for.",
+      "type": "number"
+    }
+  },
+  "required": [
+    "parameter",
+    "requested",
+    "applied"
+  ],
+  "type": "object"
+}

Previous 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."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. When a returned clip has no station ID, why: GDELT returned it without a station label, or its station catalog did not load or has no entry for the named label — with how to look the ID up. Absent when a non-empty result set fit under both the cap and the budget, no clip was dropped as out of window, and every clip carries its station ID."

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."

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."

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."

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"
+]

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."

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"
+}

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`: Exactly one of startDatetime / endDatetime was supplied. `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: `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."

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`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `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: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `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."

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`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler."New 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`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT TV API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "no_clips",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_clips",
+  "invalid_date_range",
+  "invalid_query",
+  "gdelt_rate_limited",
+  "gdelt_unavailable"
+]

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "clips",
+      "effectiveQuery",
+      "totalCount"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_clips`: No TV clips matched the query in the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query — no station was selected, or the query string is malformed. `gdelt_unavailable`: GDELT TV API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_clips",
+            "invalid_date_range",
+            "invalid_query",
+            "gdelt_unavailable"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "clips",
-  "effectiveQuery",
-  "totalCount"
-]

Previous value: -"Maximum number of clips to return (1–3000)."New 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."

Added value: +{
+  "description": "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.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One window to re-query with the same query string.",
+    "properties": {
+      "endDatetime": {
+        "description": "End of this window in GDELT format YYYYMMDDHHMMSS.",
+        "type": "string"
+      },
+      "startDatetime": {
+        "description": "Start of this window in GDELT format YYYYMMDDHHMMSS.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "startDatetime",
+      "endDatetime"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Previous value: -"Recovery hint when no clips matched. Absent on successful responses."New 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."

Previous value: -"End datetime in GDELT format YYYYMMDDHHMMSS. Must pair with startDatetime."New value: +"End datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200131235959). Must pair with startDatetime; supplying only one of the two is rejected."

Added value: +"^\\d{14}$"

Previous value: -"Start datetime in GDELT format YYYYMMDDHHMMSS. Must pair with endDatetime."New value: +"Start datetime in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20200101000000). Must pair with endDatetime; supplying only one of the two is rejected."

Added value: +"^\\d{14}$"

Previous value: -"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]). Omit for all stations. Use gdelt_list_tv_stations to see valid IDs."New value: +"Station IDs to filter to (e.g. [\"CNN\", \"FOXNEWS\"]). The GDELT TV API requires at least one station — supply it here, or embed a station: selector directly in query. Omitting both is rejected; it does not fall back to all stations. Use gdelt_list_tv_stations to see valid IDs."

Added value: +{
+  "description": "Echoed query string for use in follow-up calls.",
+  "type": "string"
+}

Removed value: -{
-  "description": "Echoed query string.",
-  "type": "string"
-}

Added value: +{
+  "description": "Number of clips returned.",
+  "type": "number"
+}

Removed value: -{
-  "description": "Number of clips returned.",
-  "type": "number"
-}

Previous value: -[
-  "query",
-  "clips",
-  "totalReturned"
-]New value: +[
+  "clips",
+  "effectiveQuery",
+  "totalCount"
+]