Added value: +{
+  "description": "Each source tried for this call, in order. Present only when the DOC API did not answer with data and the mirror was consulted.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One source's outcome for this call.",
+    "properties": {
+      "detail": {
+        "description": "Why, when the outcome has a reason: DOC's failure message or the mirror's.",
+        "type": "string"
+      },
+      "outcome": {
+        "description": "What the source did: answered, empty (answered with no matches), rate_limited, or unavailable; or why the mirror could not answer: not_ready (no completed sync), not_compiled (the query or its timespan is in a form the mirror cannot evaluate), outside_coverage (the window lies outside the days it holds), store_error.",
+        "enum": [
+          "answered",
+          "empty",
+          "rate_limited",
+          "unavailable",
+          "not_ready",
+          "not_compiled",
+          "outside_coverage",
+          "store_error"
+        ],
+        "type": "string"
+      },
+      "source": {
+        "description": "The source tried.",
+        "enum": [
+          "doc_api",
+          "gkg_mirror"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "source",
+      "outcome"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Added value: +{
+  "additionalProperties": false,
+  "description": "Present only when the mirror answered less than the requested window. Every count, share, and article in this response comes from answeredStart through answeredEnd; nothing outside it, or in a missing slot, was counted.",
+  "properties": {
+    "answeredEnd": {
+      "description": "End of the window the mirror answered, ISO 8601 UTC.",
+      "type": "string"
+    },
+    "answeredStart": {
+      "description": "Start of the window the mirror answered, ISO 8601 UTC.",
+      "type": "string"
+    },
+    "missingSlots": {
+      "description": "15-minute GKG slots inside the answered window that the mirror holds no data for.",
+      "type": "number"
+    },
+    "requestedEnd": {
+      "description": "End of the requested window, ISO 8601 UTC.",
+      "type": "string"
+    },
+    "requestedStart": {
+      "description": "Start of the requested window, ISO 8601 UTC.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "requestedStart",
+    "requestedEnd",
+    "answeredStart",
+    "answeredEnd",
+    "missingSlots"
+  ],
+  "type": "object"
+}

Previous value: -"Guidance on an incomplete or empty result. When no articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the maxRecords cap was reached, raise maxRecords below the 250 ceiling or narrow the date window at it. Absent when a non-empty result set is below the cap and no article was dropped as out of window."New value: +"Guidance on an incomplete or empty result. When no articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the maxRecords cap was reached, raise maxRecords below the 250 ceiling or narrow the date window at it. When the server's local GKG mirror answered (source: gkg_mirror), why, and how its answer differs from the DOC API's. Absent when a non-empty result set from the DOC API is below the cap and no article was dropped as out of window."

Added value: +{
+  "description": "Where this answer came from: doc_api, the GDELT DOC API, or gkg_mirror, the server's local mirror of GDELT's Global Knowledge Graph, which answers when the DOC API refuses the request or returns nothing. Present on every answer while the server runs a mirror; absent otherwise.",
+  "enum": [
+    "doc_api",
+    "gkg_mirror"
+  ],
+  "type": "string"
+}

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 articles to fetch (1–250; a value up to 2500 runs at 250, and the response says so in limitClamp). The response carries as many of them as fit its 48,000-byte budget. 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."New value: +"Maximum number of articles to fetch. Defaults to 75; values above 250 run at 250 with a limitClamp disclosure unless clamping is disabled. Every fetched in-window record is returned. 250 is GDELT's hard per-call ceiling, with no cursor; split a query that fills it into narrower startDatetime/endDatetime windows."

Removed value: -2500

Added value: +1

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

Previous value: -"Windows to re-run this query against, one at a time, when more articles 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 article, reaching back to the second it was published, so articles from that second come back again — or, when resuming there cannot reach a new article, one window skipping past that second. Otherwise — maxRecords at its 250 ceiling, or a cut under any other sort — the queried window halved, overlapping by one second so no article falls through the seam. Either way, de-duplicate by url. Absent when no window is known, or none would reach further."New value: +"Windows to re-run this query against when maxRecords reaches its 250 ceiling: the queried window halved, overlapping by one second so no article falls through the seam. De-duplicate by url. Absent when no window is known or narrowing cannot reach further articles."

Previous value: -"Guidance on an incomplete or empty result. When no articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the response was cut to its 48,000-byte budget, how many articles it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more articles may exist — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget and no article was dropped as out of window."New value: +"Guidance on an incomplete or empty result. When no articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the maxRecords cap was reached, raise maxRecords below the 250 ceiling or narrow the date window at it. Absent when a non-empty result set is below the cap and no article was dropped as out of window."

Removed value: -{
-  "description": "Articles GDELT returned inside the window that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting articles dropped for falling outside an explicit window. Absent when every in-window article fit.",
-  "type": "number"
-}

Previous value: -"Maximum number of articles to fetch (1–250); the response carries as many of them as fit its 48,000-byte budget. 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."New value: +"Maximum number of articles to fetch (1–250; a value up to 2500 runs at 250, and the response says so in limitClamp). The response carries as many of them as fit its 48,000-byte budget. 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."

Previous value: -250New value: +2500

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 articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the response was cut to its 48,000-byte budget, how many articles it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more articles may exist — a higher maxRecords below the 250 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 articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the response was cut to its 48,000-byte budget, how many articles it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more articles may exist — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when a non-empty result set fit under both the cap and the budget and no article was dropped as out of window."

Previous value: -"Search query. Supports GDELT operators: phrases (\"bird flu\"), boolean OR ((flu OR pandemic)), sourcecountry:china, sourcelang:spanish, domain:who.int, theme:DISEASE_OUTBREAK, tone<-5, near20:\"flu virus\", repeat3:\"outbreak\"."New value: +"Search query. Supports GDELT operators: phrases (\"bird flu\"), boolean OR ((flu OR pandemic)), sourcecountry:china, sourcelang:spanish, domain:who.int, theme:TAX_DISEASE_OUTBREAK (GKG theme identifiers come from gdelt_search_themes), tone<-5, near20:\"flu virus\", repeat3:\"outbreak\"."

Previous value: -"Maximum number of articles to return (1–250). 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 must be split into narrower startDatetime/endDatetime windows instead."New value: +"Maximum number of articles to fetch (1–250); the response carries as many of them as fit its 48,000-byte budget. 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 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 250 ceiling. The halves overlap by one second so no article falls through the seam; an article published on that second can come back in both, so de-duplicate by url. 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 articles 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 article, reaching back to the second it was published, so articles from that second come back again — or, when resuming there cannot reach a new article, one window skipping past that second. Otherwise — maxRecords at its 250 ceiling, or a cut under any other sort — the queried window halved, overlapping by one second so no article falls through the seam. Either way, de-duplicate by url. Absent when no window is known, or none would reach further."

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within 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 string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `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 DOC 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 string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `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 DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "no_articles",
-  "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 articles may exist, naming the route to them — a higher maxRecords below the 250 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 articles matched, how to broaden the query or window. When GDELT returned articles dated outside an explicit startDatetime/endDatetime window, how many were dropped. When the response was cut to its 48,000-byte budget, how many articles it withheld and the route to them. When the maxRecords cap was reached on an uncut response, that more articles may exist — a higher maxRecords below the 250 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": "Articles GDELT returned inside the window that this response withheld to stay within its 48,000-byte budget — fetched minus returned, not counting articles dropped for falling outside an explicit window. Absent when every in-window article fit.",
+  "type": "number"
+}

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `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 DOC 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_articles`: No articles matched the query within 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 string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `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 DOC 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_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC 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_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `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 DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Previous value: -"Sort order: relevance (default), date (newest first), social (most socially shared)."New value: +"Sort order: relevance (default), dateDesc/dateAsc, toneDesc/toneAsc, or hybridRel (GDELT hybrid relevance and recency)."

Previous value: -[
-  "date",
-  "relevance",
-  "social"
-]New value: +[
+  "relevance",
+  "dateDesc",
+  "dateAsc",
+  "toneDesc",
+  "toneAsc",
+  "hybridRel"
+]

Previous value: -"Time window relative to now, e.g. \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum is 3 months (the full DOC API window). Defaults to the full 3-month window."New value: +"Time window relative to now, minimum \"15min\"; other examples: \"24h\", \"7d\", \"1m\". Ignored when startDatetime/endDatetime are set. Maximum is 3 months (the full DOC API window). Defaults to the full 3-month window."

Previous value: -"Machine-readable failure mode. Declared by this tool: `no_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC 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_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_rate_limited`: GDELT rejected the request because its one-request-per-five-seconds limit was reached. `gdelt_unavailable`: GDELT DOC API is unreachable or temporarily returned no usable data. Other values are possible when a failure originates below the handler."

Previous value: -[
-  "no_articles",
-  "invalid_date_range",
-  "invalid_query",
-  "gdelt_unavailable"
-]New value: +[
+  "no_articles",
+  "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": [
+      "articles",
+      "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_articles`: No articles matched the query within the specified time range. `invalid_date_range`: Exactly one of startDatetime / endDatetime was supplied. `invalid_query`: GDELT rejected the query string as malformed — bad keyword length, unbalanced parentheses, or an illegal character. `gdelt_unavailable`: GDELT DOC API is unreachable or rate-limited. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_articles",
+            "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: -[
-  "articles",
-  "effectiveQuery",
-  "totalCount"
-]

Previous value: -"Maximum number of articles to return (1–250)."New value: +"Maximum number of articles to return (1–250). 250 is GDELT's hard per-call ceiling, not a page size — there is no cursor past it, so a query that fills 250 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 250 ceiling. The halves overlap by one second so no article falls through the seam; an article published on that second can come back in both, so de-duplicate by url. 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 articles matched — echoes filters and suggests how to broaden. Absent on successful responses."New value: +"Disclosure that the maxRecords cap was reached and more articles may exist, naming the route to them — a higher maxRecords below the 250 ceiling, or a narrower date window at it. Absent when the full result set fit under the cap."

Previous value: -"End of date range in GDELT format YYYYMMDDHHMMSS (e.g. 20240131235959). Must be used together with startDatetime."New value: +"End of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240131235959). Must be supplied together with startDatetime; supplying only one of the two is rejected."

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

Previous value: -"Start of date range in GDELT format YYYYMMDDHHMMSS (e.g. 20240101000000). Must be used together with endDatetime."New value: +"Start of date range in GDELT format YYYYMMDDHHMMSS — exactly 14 digits, no separators (e.g. 20240101000000). Must be supplied together with endDatetime; supplying only one of the two is rejected."

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

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

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

Added value: +{
+  "description": "Number of articles returned in this response.",
+  "type": "number"
+}

Removed value: -{
-  "description": "Number of articles returned in this response.",
-  "type": "number"
-}

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