Skip to main content
POST
/
api
/
v2
/
briefs
cURL
curl -X POST "https://gdeltcloud.com/api/v2/briefs" \
  -H "Authorization: Bearer $GDELT_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope_text":"Monitor Red Sea maritime disruption risk across Yemen and the Gulf of Aden.","time_window":"7d","baseline_window":"30d","audience":"executive","countries":["YEM","SAU"]}'
{
  "id": "brief_123",
  "status": "queued",
  "brief_type": "monitoring_brief",
  "title": "Red Sea maritime disruption watch",
  "created_at": "2026-06-08T14:00:00Z",
  "web_url": "https://gdeltcloud.com/briefs/brief_123",
  "public_url": null,
  "message": "Brief generation started."
}

Authorizations

​
Authorization
string
header
required

GDELT Cloud API key. Send as Authorization: Bearer gdelt_sk_....

Body

application/json
​
scope_text
string
required

One or two plain sentences: the situation, where it is, who/what is affected, and the decision it informs.

Required string length: 8 - 2400
Example:

"Monitor Red Sea maritime disruption risk to shipping across Yemen, the Red Sea, and the Gulf of Aden."

​
time_window
enum<string>
default:24h

Recent window the Brief analyses.

Available options:
6h,
24h,
72h,
7d,
30d
​
baseline_window
enum<string>

Earlier comparison window for change detection.

Available options:
7d,
14d,
30d
​
audience
enum<string>
default:executive
Available options:
executive,
analyst,
operator
​
depth
enum<string>
default:standard
Available options:
skim,
standard,
detailed
​
countries
string[]

ISO-3 country codes to scope the Brief.

Example:
["YEM", "SAU"]
​
regions
string[]
​
sectors
string[]
​
search_topics
string[]

Free-text focus terms/phrases that bias retrieval.

Example:
["port congestion", "tanker insurance"]
​
actors
string[]

Named actors to emphasize.

Example:
["Houthi", "Maersk"]
​
entities
string[]

Named people or organizations to emphasize.

​
locations
string[]

Plain-English sub-country locations.

​
assets
string[]

Named facilities or infrastructure.

​
public_link
boolean
default:false

When true, also mint a public shareable report URL.

​
title
string

Optional; auto-generated from scope_text when omitted.

​
brief_type
string
default:monitoring_brief

Optional; defaults to monitoring_brief, the only generally-available type.

Response

Brief generation started.

​
id
string
​
status
string
Example:

"queued"

​
brief_type
string
​
title
string
​
created_at
string
​
web_url
string
​
public_url
string | null
​
message
string