curl --request GET \
--url https://gdeltcloud.com/api/v2/entities/{entity_id}/offices \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/entities/{entity_id}/offices"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/entities/{entity_id}/offices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": []
}List Entity Offices
Every public office one entity has held, as the publishers assert it. {entity_id} accepts a spine e_… id, a news wiki: / llm: id, or a wikipedia_url, resolved through the same arbiter every other surface uses — a merged-away alias still finds its rows. An entity that resolves but holds no office answers data: [] with meta.checked: true; one with no spine identity to look under answers data: [] with meta.checked: false; one that does not resolve at all is 404 ENTITY_NOT_FOUND, never an empty 200.
curl --request GET \
--url https://gdeltcloud.com/api/v2/entities/{entity_id}/offices \
--header 'Authorization: Bearer <token>'import requests
url = "https://gdeltcloud.com/api/v2/entities/{entity_id}/offices"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://gdeltcloud.com/api/v2/entities/{entity_id}/offices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"data": []
}Authorizations
GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....
Path Parameters
The entity id.
Query Parameters
Restrict to office-holders the PUBLISHER asserts as current, ended or unknown. unknown is a real bucket, not a synonym for current: the source did not say, and nothing here infers currency from a missing end_date. Combine with as_of to ask "current AND in office on that date" — the two are independent predicates. Matched case-insensitively. Full value list: https://docs.gdeltcloud.com/reference/enums#office_holder_status
current, ended, unknown VALID TIME — who HELD the office on this date (YYYY-MM-DD), read from the start/end dates the publisher states. This is NOT knowledge-time replay: it is not routed through the can_use_asof gate and does not answer "what did we know then". An office-holder with no published start date cannot be placed on a date and is EXCLUDED rather than guessed — meta.undated_office_holders counts how many the date could not see. A future date is accepted and reads as "still in office as far as the source has published".
Maximum office-holders to return. Default 100, max 200; truncated: true when the entity has more. Note: validation is owned by the endpoint service because it depends on composed or cross-parameter state; the published error semantics above still apply.
1 <= x <= 200Response
Success