{"uid":"cap_bHtQ7dsD--hFe7tzBSOp3","slug":"gdelt-news-sentiment-timeline-api-3d2fd51c","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://news-x402.com/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":{"request":{"input":{"type":"http","method":"GET","queryParams":{"topic":"artificial intelligence","timespan":"7d"}}},"response":{"topic":"artificial intelligence","timeline":[],"timespan":"7d"}},"exampleRequest":{"topic":"artificial intelligence","timespan":"7d"},"tags":["x402"],"displayCostAmount":"0.02","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"settled","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_5_HQH71g3XrhKl61YDrhj","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.02","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns a time-series of average news sentiment (tone) for a given topic, optionally filtered by country and time window, drawn from GDELT global news data","exampleAgentPrompt":"Show me the daily news sentiment timeline for 'Ukraine' over the past 7 days — I want to see how the average media tone has shifted day by day.","exampleUseCases":[{"title":"Track competitor brand sentiment shifts","prompt":"Pull the news sentiment for our main competitor over the last 30 days so I can see if media coverage is getting more positive or negative — give me a weekly breakdown to spot any turning points."},{"title":"Monitor geopolitical crisis coverage tone","prompt":"I need to track how global news tone on the Israel-Palestine conflict has changed week by week for the past 3 months — help me understand if coverage is becoming more negative or stabilizing."},{"title":"Assess market sentiment for ESG investing","prompt":"Show me the daily average news sentiment for 'renewable energy companies' over the past 14 days — I'm trying to gauge if investor sentiment is improving based on recent media coverage trends."}],"resultDescription":"A JSON object containing the topic string, the timespan used, and a timeline array where each element has a date (ISO timestamp) and avg_tone (a float, negative = negative tone, positive = positive tone) representing average GDELT news sentiment for that period.","failureModes":["Missing required 'topic' parameter returns a 400 or schema validation error","Invalid timespan enum value (e.g. '2d') may return an error or default to 24h","Invalid ISO country code may return empty results or be silently ignored","Payment not included or insufficient USDC triggers 402 Payment Required response","Topic with no GDELT coverage in the time window returns an empty timeline array","Service unavailability or GDELT upstream issues may cause 5xx errors"],"whenToPreferThis":"Use this endpoint when you need a quantitative time-series of news sentiment (tone scores) for a specific topic rather than just headlines or article lists. Ideal for trend analysis, geopolitical monitoring, and AI agent workflows that need structured numeric sentiment data with no API key setup — just pay per query in USDC on Base.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T12:31:42.514Z","isFirstParty":false}