curl --request POST \
--url https://gdeltcloud.com/api/v2/situations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"story_id": "story_123"
}
'import requests
url = "https://gdeltcloud.com/api/v2/situations"
payload = { "story_id": "story_123" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({story_id: 'story_123'})
};
fetch('https://gdeltcloud.com/api/v2/situations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"situation_uid": "sit_example",
"created": true,
"reused": false,
"added": 4,
"considered": 7,
"quota_units": 5,
"story_count": 5,
"empty_reason": null
}Create or expand a shared Situation
Accepts a strict JSON body containing story_id or event_uid, optional direction (back or forward), and optional situation_uid for explicit expansion. An Event with several supporting Stories returns 409 and requires story_id selection. An existing canonical Situation is reused for 0 QU when situation_uid is omitted. Creation or explicit expansion costs 5 QU and requires a paid subscription or active trial. Admitted work requires an Idempotency-Key header (8–128 letters, digits or ._:-); replay uses the recorded response, concurrent work returns 409, and another body with the same key returns 409. Every success includes story_count. Failures before durable authoring completion release quota reservations; an edition publication failure does not undo successful authoring or repeat judge work. The shared stored identity is public to all readers; this does not create a private copy.
curl --request POST \
--url https://gdeltcloud.com/api/v2/situations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"story_id": "story_123"
}
'import requests
url = "https://gdeltcloud.com/api/v2/situations"
payload = { "story_id": "story_123" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({story_id: 'story_123'})
};
fetch('https://gdeltcloud.com/api/v2/situations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"situation_uid": "sit_example",
"created": true,
"reused": false,
"added": 4,
"considered": 7,
"quota_units": 5,
"story_count": 5,
"empty_reason": null
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Headers
Stable key for one admitted creation or expansion. Reuse the same key and body to retry a timed-out request; a different body needs a new key.
8 - 128^[A-Za-z0-9._:-]{8,128}$Body
Response
Created, expanded, or reused Situation. Reuse costs 0 QU; adjudication costs 5 QU. Every success includes story_count.
true 0