{"uid":"cap_CA-JDkr1J-1TkwbBAlW8z","slug":"gdelt-news-sentiment-timeline-api-5c7fa962","name":"GDELT News Sentiment Timeline API","description":"AI-friendly JSON API for global news intelligence. Built on GDELT (free public source), optimized for AI agents — clean responses, 5 use-case endpoints, parallel-aggregated entity graphs, no rate limits, no API keys. Pay-per-query in USDC on Base mainnet via x402.","url":"https://gdelt-x402-api.planbdj.workers.dev/news/sentiment","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET","HEAD","DELETE"],"type":"string"},"queryParams":{"type":"object","required":["topic"],"properties":{"topic":{"type":"string","description":"Search query"},"country":{"type":"string","description":"Optional ISO country code filter (e.g. US, FR, RU)"},"timespan":{"enum":["15min","1h","4h","24h","3d","7d","1w","1m","3m"],"type":"string","description":"Time window (default 24h)"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","required":["topic","timespan","timeline"],"properties":{"topic":{"type":"string"},"timeline":{"type":"array","items":{"type":"object","required":["date","avg_tone"],"properties":{"date":{"type":"string"},"avg_tone":{"type":"number"}}}},"timespan":{"type":"string"}}}}}}},"responseSchema":{"type":"json","example":{"topic":"ukraine","timeline":[{"date":"2026-04-30T00:00:00","avg_tone":-2.1}],"timespan":"7d"}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.02","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.02/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.02","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_utOuJg-Y4Q2VYQBhfWn_G","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.02","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns a day-by-day sentiment tone timeline for a given news topic using GDELT global news data","exampleAgentPrompt":"Pull the GDELT news sentiment timeline for 'Ukraine' over the past 7 days — I want to see how the average tone of global coverage has shifted day by day.","exampleUseCases":[{"title":"Geopolitical crisis media monitoring","prompt":"Show me the daily sentiment trend for news about 'Gaza' over the last 7 days — I want to see if coverage tone has been getting more negative or stabilizing."},{"title":"Brand reputation tracking","prompt":"Get me a sentiment timeline for 'Tesla' in the news over the past 14 days — I need to know if the average tone of coverage has been improving since last week's announcement."},{"title":"Macro event sentiment analysis","prompt":"What's the GDELT sentiment trend for 'Federal Reserve' news over the last 7 days? I want to see the day-by-day average tone leading up to the rate decision."}],"resultDescription":"A JSON object containing the queried topic, the requested timespan, and an array of daily data points each with a UTC date and an average GDELT tone score (negative values indicate negative sentiment, positive values indicate positive sentiment).","failureModes":["Topic string too vague — returns flat or noisy tone values with little signal","Timespan parameter malformed or unsupported — may return error or empty timeline","No GDELT coverage for topic in the requested period — empty timeline array","Network timeout on GDELT upstream aggregation — transient 5xx error","Payment failure or insufficient USDC balance — 402 or authorization error"],"whenToPreferThis":"Choose this endpoint when you need a quantified, day-by-day sentiment trend for a specific news topic using a global, multi-source news corpus. It is ideal for macro-level media monitoring, geopolitical sentiment tracking, or brand reputation trends where you want a time series of tone rather than individual article content. Prefer it over social-media sentiment APIs when journalistic sourcing and global coverage breadth matter, and over full-text news APIs when you only need the aggregated emotional signal rather than article bodies.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-13T18:31:31.720Z","isFirstParty":false}