{"openapi":"3.0.3","info":{"title":"News signals and trends (Agent Data API)","description":"Signals derived from GDELT's 15-minute global news coding: tone in basis points, mention volume against a 30-day baseline, novelty and trending for organisations, tickers, crypto assets, central banks, governments and topics; trending people and topics ranked by attention spike (Wikipedia pageviews, GDELT, Google Trends, Mastodon); and the 50 most-covered stories per window. No article text.","version":"2026.11.09"},"paths":{"/api/v1/entities":{"get":{"tags":["News signals and trends"],"summary":"Tracked entities","description":"Organisations, tickers, crypto assets, central banks, governments and topics we score, with ids, aliases and 30-day baselines. Filter by text or kind. Refreshes every 24 hours.","operationId":"news_search_entities","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Q","examples":["nvidia"]}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Kind","description":"org, ticker, crypto, central_bank, government, topic","examples":["ticker"]},"description":"org, ticker, crypto, central_bank, government, topic"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.005","x-price":{"price_micro":5000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_entities","x-cadence":"Refreshes every 24 hours."}},"/api/v1/sentiment/{entity}":{"get":{"tags":["News signals and trends"],"summary":"News sentiment and volume for an entity","description":"Mentions in the window, the 30-day baseline expectation, volume ratio and novelty in basis points, mention-weighted tone, tone change against the baseline and the top GDELT themes. Refreshes every 15 minutes.","operationId":"news_sentiment","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"entity","in":"path","required":true,"schema":{"type":"string","title":"Entity"},"example":"org_nvidia"},{"name":"window","in":"query","required":false,"schema":{"type":"string","description":"1h, 24h or 7d","example":"24h","default":"24h","title":"Window"},"description":"1h, 24h or 7d"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_sentiment","x-cadence":"Refreshes every 15 minutes."}},"/api/v1/tickers/{symbol}/news-score":{"get":{"tags":["News signals and trends"],"summary":"News score for a ticker or crypto symbol","description":"The sentiment block for the entity behind a ticker (NVDA, JPM) or crypto asset symbol (BTC): mentions against baseline, volume ratio, novelty, tone and tone change, top themes. Refreshes every 15 minutes.","operationId":"news_ticker_score","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","title":"Symbol"},"example":"NVDA"},{"name":"window","in":"query","required":false,"schema":{"type":"string","example":"24h","default":"24h","title":"Window"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_ticker_score","x-cadence":"Refreshes every 15 minutes."}},"/api/v1/entities/trending":{"get":{"tags":["News signals and trends"],"summary":"Entities with unusual news volume","description":"Entities ranked by novelty (volume over their 30-day baseline) in the window, with mentions and tone. Filter by kind. Refreshes every 15 minutes.","operationId":"news_trending","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Kind","examples":["ticker"]}},{"name":"window","in":"query","required":false,"schema":{"type":"string","example":"24h","default":"24h","title":"Window"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.015","x-price":{"price_micro":15000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_trending","x-cadence":"Refreshes every 15 minutes."}},"/api/v1/events":{"get":{"tags":["News signals and trends"],"summary":"GDELT events","description":"CAMEO-coded events from the 15-minute export, newest first: actor codes and names, event code, Goldstein scale (milli), mentions, tone (bps), country and source URL. Filter by actor code, country or since. Refreshes every 15 minutes.","operationId":"events_news_api_v1_events_get","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"actor","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Actor","description":"CAMEO actor code or name, e.g. USA, CHN, GOV","examples":["USA"]},"description":"CAMEO actor code or name, e.g. USA, CHN, GOV"},{"name":"country","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Country","description":"ActionGeo country code","examples":["US"]},"description":"ActionGeo country code"},{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"title":"Since","examples":["2026-11-09T00:00:00"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_events","x-cadence":"Refreshes every 15 minutes."}},"/api/v1/sentiment/{entity}/history":{"get":{"tags":["News signals and trends"],"summary":"Sentiment history (Pro)","description":"Mentions and tone per 15-minute window (last 90 days) or per day, newest first. Point in time by construction: a window holds only records GDELT published in it. Refreshes every 15 minutes.","operationId":"news_sentiment_history","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"entity","in":"path","required":true,"schema":{"type":"string","title":"Entity"},"example":"org_nvidia"},{"name":"interval","in":"query","required":false,"schema":{"type":"string","description":"15m or 1d","example":"1d","default":"1d","title":"Interval"},"description":"15m or 1d"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"title":"From","examples":["2026-10-01T00:00:00"]}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time","nullable":true,"title":"To"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"default":200,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.02","x-price":{"price_micro":20000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_sentiment_history","x-cadence":"Refreshes every 15 minutes.","x-cache-ttl-s":1800}},"/api/v1/trending/people":{"get":{"tags":["News signals and trends"],"summary":"Trending public figures","description":"People with the biggest attention spike against their 30-day baseline: Wikipedia daily pageviews blended with news coverage, classified through Wikidata occupations into celebrity, politics, sport, business or other. Only people with a Wikipedia article and a Wikidata id are ever listed. Refreshes every 60 minutes.","operationId":"news_trending_people","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Category","description":"celebrity, politics, sport, business, other","examples":["celebrity"]},"description":"celebrity, politics, sport, business, other"},{"name":"window","in":"query","required":false,"schema":{"type":"string","example":"24h","default":"24h","title":"Window"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.015","x-price":{"price_micro":15000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_trending_people","x-cadence":"Refreshes every 60 minutes."}},"/api/v1/trending/topics":{"get":{"tags":["News signals and trends"],"summary":"Trending topics by region","description":"Top daily searches (approximate traffic and three headlines each, titles and links only) and trending Mastodon tags and shared links, ranked by attention. Regions US, AU, GB. Refreshes every 60 minutes.","operationId":"news_trending_topics","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"region","in":"query","required":false,"schema":{"type":"string","example":"US","default":"US","title":"Region"}},{"name":"window","in":"query","required":false,"schema":{"type":"string","example":"24h","default":"24h","title":"Window"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.015","x-price":{"price_micro":15000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_trending_topics","x-cadence":"Refreshes every 60 minutes."}},"/api/v1/top-stories":{"get":{"tags":["News signals and trends"],"summary":"Most-covered stories","description":"Up to 50 stories ranked by how many GDELT records cited the URL in the window: title, link, publisher domain, tone and the tracked entities named. Titles and links only, never article text. Refreshes every 15 minutes.","operationId":"news_top_stories","security":[{"ApiKeyAuth":[]},{}],"parameters":[{"name":"window","in":"query","required":false,"schema":{"type":"string","description":"1h, 6h or 24h","example":"6h","default":"6h","title":"Window"},"description":"1h, 6h or 24h"},{"name":"entity","in":"query","required":false,"schema":{"type":"string","nullable":true,"title":"Entity","examples":["org_nvidia"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment required (x402). Body lists accepts[] with USDC amount, network and payTo."}},"x-price-usdc":"0.01","x-price":{"price_micro":10000,"asset":"USDC","network":"eip155:8453"},"x-payment":"x402","x-payment-route-id":"news_top_stories","x-cadence":"Refreshes every 15 minutes."}}},"components":{"schemas":{"APIKeyCreate":{"properties":{"email":{"type":"string","title":"Email","description":"Where this key belongs. Agents: your human's real address, else your own mailbox.","example":"owner@yourcompany.com"}},"type":"object","required":["email"],"title":"APIKeyCreate"},"AgentSubscribeRequest":{"properties":{"plan":{"type":"string","title":"Plan","description":"pass_1h, pass_1d or pass_7d","example":"pass_1d"}},"type":"object","required":["plan"],"title":"AgentSubscribeRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"servers":[{"url":"https://agentdataapi.com/news"}],"tags":[{"name":"News signals and trends","description":"GDELT-derived sentiment and attention signals per entity and ticker, trending people and topics, and the most-covered stories."}]}