Tools (5)

search_articles
get_event_timeline
get_tone_timeline
get_source_country_breakdown
report_feedback

search_articles

Search global news articles across 150+ countries and 65+ languages.

GDELT monitors news media worldwide, updated every 15 minutes. Returns
articles with source, date, tone score, and thumbnail image.

Examples:
search_articles("artificial intelligence") → AI coverage from the last 24h
search_articles("oil prices", timespan="7d", sort="ToneDesc") → positive oil news from the past week
search_articles("elections", source_country="france") → French election coverage

Returns:
List of articles with URL, title, source, language, date, and tone score.

Parameter	Type	Required	Description
`query`	`string`	required	Search query — keywords, exact phrases in quotes, or GDELT syntax (e.g. "climate change", "domain:bbc.com").
`timespan`	`string`	optional	Lookback window: "24h" (default), "7d", "2w", "3m". Max 3 months. (default: "24h")
`max_results`	`integer`	optional	Max articles to return (default 25, max 250). (default: 25)
`sort`	`string`	optional	Sort order: "HybridRel" (relevance, default), "DateDesc", "DateAsc", "ToneDesc", "ToneAsc". (default: "HybridRel")
`source_country`	`any`	optional	Filter by source country (e.g. "US", "france", "norway"). Optional.
`source_lang`	`any`	optional	Filter by source language (e.g. "english", "spanish"). Optional.

Request Body

{
  "query": "example"
}

get_event_timeline

Get media coverage volume over time — tracks how a story rises and falls.

Returns a time series of article counts matching the query. Useful for
detecting spikes in coverage, comparing before/after events, or monitoring
ongoing stories.

Examples:
get_event_timeline("tariffs") → tariff coverage over the past week
get_event_timeline("earthquake", timespan="30d") → earthquake coverage, monthly view
get_event_timeline("bitcoin", smooth=5) → smoothed Bitcoin coverage trend

Returns:
Time series with date and article volume at each time step.

Parameter	Type	Required	Description
`query`	`string`	required	Search query — keywords or GDELT syntax.
`timespan`	`string`	optional	Lookback window: "7d" (default), "24h", "2w", "3m". Max 3 months. (default: "7d")
`smooth`	`integer`	optional	Moving-average smoothing (0-30 time steps). 0 = no smoothing (default). (default: 0)

Request Body

{
  "query": "example"
}

get_tone_timeline

Get media tone/sentiment over time for a topic.

Tone ranges from negative (critical/alarming) to positive (optimistic/favorable).
Most news falls between -10 and +5. Tracks how public sentiment shifts
around events, announcements, or crises.

Examples:
get_tone_timeline("Federal Reserve") → Fed sentiment over the past week
get_tone_timeline("Tesla", timespan="30d") → Tesla media sentiment, monthly
get_tone_timeline("war", timespan="3m", smooth=3) → smoothed conflict tone

Returns:
Time series with date and tone score at each time step.

Parameter	Type	Required	Description
`query`	`string`	required	Search query — keywords or GDELT syntax.
`timespan`	`string`	optional	Lookback window: "7d" (default), "24h", "2w", "3m". Max 3 months. (default: "7d")
`smooth`	`integer`	optional	Moving-average smoothing (0-30 time steps). 0 = no smoothing (default). (default: 0)

Request Body

{
  "query": "example"
}

get_source_country_breakdown

Get which countries' media are covering a topic, ranked by volume.

Shows where news about a topic originates from — which countries'
media outlets are writing about it most. Useful for understanding
regional interest and geographic spread of coverage.

Examples:
get_source_country_breakdown("trade war") → which countries cover trade war most
get_source_country_breakdown("AI regulation", timespan="7d") → AI regulation coverage by country
get_source_country_breakdown("climate summit") → which nations' media cover climate talks

Returns:
List of countries sorted by coverage volume (highest first).

Parameter	Type	Required	Description
`query`	`string`	required	Search query — keywords or GDELT syntax.
`timespan`	`string`	optional	Lookback window: "24h" (default), "7d", "3m". Max 3 months. (default: "24h")

Request Body

{
  "query": "example"
}

report_feedback

Report a bug, feature request, or general feedback for this data source.

Use this when something doesn't work as expected, when you'd like
a new feature, or when you have suggestions for improvement.

Args:
feedback: Describe the issue or suggestion.
feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	`string`	required
`feedback_type`	`string`	optional	(default: "general")

Request Body

{
  "feedback": "example"
}

Quick Start

Shell

curl -X POST "https://context.gnist.ai/rest/gdelt/search_articles" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"query": "example"}'

Python

import httpx

resp = httpx.post(
    "https://context.gnist.ai/rest/gdelt/search_articles",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={
  "query": "example"
},
)
print(resp.json())