--- title: "News Feed" description: "Integrate market-aware news feeds into partner discovery and market detail experiences" --- > **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version. AGG News Feed connects real-world news to tradeable prediction markets. Use it to power category feeds, market detail pages, related-news modules, and agent workflows with articles that are already linked to markets and summarized for market impact. Instead of showing generic news links, partner apps can show why a story may matter to a specific prediction market. News Feed is an app-tier Discovery API for market-aware articles, live market links, and market-impact summaries. ## Public API access All News Feed endpoints require your app header: Your AGG app identifier. No user JWT is required. App venue and category settings are applied automatically, so responses only include markets your app is configured to show. ## Endpoint map | API Reference | Use when | | --- | --- | | [List feeds](/api-reference/discovery/list-available-news-feeds-with-ids-and-item-counts) | You want the available feed categories and item counts. | | [Get article feed](/api-reference/discovery/article-centric-news-feed-for-a-category-latest-articles-with-linked-markets-and-live-prices) | You want an article-first feed with linked markets for each article. | | [Get market feed](/api-reference/discovery/market-centric-news-feed-markets-grouped-with-their-news-timeline) | You want a market-first feed where each market includes recent related articles. | | [Get market news](/api-reference/discovery/get-news-articles-for-markets-with-market-impact-summaries) | You have specific markets or events and want recent articles for them. | Available categories are `politics`, `geopolitics`, `world`, `finance`, `climate`, and `entertainment`. ## What you get - Article-first feeds for discovery pages and editorial-style layouts. - Market-first feeds where each market carries its recent article timeline. - On-demand related-news lookup for specific `venueMarketIds` or `venueEventIds`. - Article metadata, publisher/source labels, images when available, publish timestamps, and links to original sources. - LLM-generated market-impact summaries and relevance scores for ranking related articles. - App-scoped filtering so disabled venues and categories do not leak into partner feeds. ## Which call should I use? Use `getMarketNews` when the user is already looking at a specific market or event. This is the call for "related news" modules on market detail pages. Use `getNewsFeed` when you want a category news feed where articles are the main object. Use `getNewsFeedMarkets` when you want a category feed where markets are the main object and each market carries its recent article timeline. Most partner integrations use both patterns: 1. Category or homepage: call `getNewsFeed("finance")` or `getNewsFeedMarkets("finance")`. 2. Market detail page: call `getMarketNews({ venueMarketIds: [market.id] })`. 3. Event detail page: collect the event's market ids, then call `getMarketNews` for the set. ## Which id should I pass? | If your UI has | Pass this field | Example request | | --- | --- | --- | | A market card or market detail object | `venueMarket.id` | `{ "venueMarketIds": ["vm_abc123"] }` | | A matched sibling market | `venueMarket.matchedVenueMarkets[].id` | `{ "venueMarketIds": ["vm_abc123", "vm_def456"] }` | | An event object | `venueEvent.id` | `{ "venueEventIds": ["ve_abc123"] }` | | An event detail with markets loaded | `venueEvent.venueMarkets[].id` | `{ "venueMarketIds": ["vm_1", "vm_2"] }` | ## Choose a feed shape Use the article feed for homepages, discovery rails, and editorial-style layouts: ```typescript const { data, nextCursor, hasMore } = await client.getNewsFeed("finance", { limit: 20, }); for (const item of data) { console.log(item.article.title); console.log(item.markets.map((market) => market.question)); } ``` Use the market feed for market pages, event pages, and category views where the market is the main object: ```typescript const { data } = await client.getNewsFeedMarkets("politics", { limit: 12, }); for (const market of data) { console.log(market.question); console.log(market.articles.map((article) => article.title)); } ``` ## Pagination and refresh Both feed shapes support the same query options: | Option | Type | Notes | | --- | --- | --- | | `limit` | `number` | Page size from `1` to `50`. | | `cursor` | `string` | Pass the previous response's `nextCursor` to fetch the next page. | | `since` | `string` | ISO timestamp for a lower time bound. | | `before` | `string` | ISO timestamp for an upper time bound. | ```typescript const firstPage = await client.getNewsFeed("world", { limit: 20 }); if (firstPage.nextCursor) { const nextPage = await client.getNewsFeed("world", { cursor: firstPage.nextCursor, limit: 20, }); } ``` For repeated refreshes of the same feed or market request, poll no more than once per minute unless the user explicitly asks for a manual refresh. ## Get related news for one market If your UI is rendering a market card or market detail page, you already have the AGG market id at `venueMarket.id`. Pass that id as `venueMarketIds`. ```typescript const news = await client.getMarketNews({ venueMarketIds: ["vm_abc123"], limit: 3, }); for (const result of news.results) { console.log(result.question); console.log(result.articles.map((article) => article.summary)); } ``` The response is grouped by market. For a single market, render the first result: ```typescript const [marketNews] = news.results; const cards = marketNews?.articles.map((article) => ({ headline: article.title, source: article.source, publishedAt: article.publishedAt, href: article.url, imageUrl: article.imageUrl, marketContext: article.summary, })) ?? []; ``` In the UI, label this module as related news for the market question: ```typescript const title = marketNews ? `Related news for ${marketNews.question}` : "Related news"; ``` For request and response details, use the [Get market news API reference](/api-reference/discovery/get-news-articles-for-markets-with-market-impact-summaries). ## Include matched venues If your market object includes `matchedVenueMarkets`, include those ids too. This lets a single market detail page show related news for the same market across venues. ```typescript const venueMarketIds = [ market.id, ...(market.matchedVenueMarkets ?? []).map((matched) => matched.id), ].slice(0, 10); const relatedNews = await client.getMarketNews({ venueMarketIds, limit: 3, }); ``` Deduplicate articles by `url` before rendering if you merge results from multiple markets: ```typescript const uniqueArticles = [ ...new Map( relatedNews.results .flatMap((result) => result.articles) .map((article) => [article.url, article]), ).values(), ]; ``` ## Get related news for an event If the user is on an event detail page, fetch the event's markets first, then request news for the markets you plan to render. ```typescript const { data: markets } = await client.getVenueMarkets({ venueEventId: "ve_abc123", status: "open", limit: 10, }); const venueMarketIds = markets .flatMap((market) => [ market.id, ...(market.matchedVenueMarkets ?? []).map((matched) => matched.id), ]) .slice(0, 10); const eventNews = await client.getMarketNews({ venueMarketIds, limit: 2, }); ``` Render each group under its market question: ```typescript for (const result of eventNews.results) { console.log(result.question); for (const article of result.articles) { console.log(article.title, article.summary); } } ``` If you only have the event id and do not need market-level control, pass `venueEventIds` directly. For the exact body shape, use the [Get market news API reference](/api-reference/discovery/get-news-articles-for-markets-with-market-impact-summaries). You can pass `venueMarketIds`, `venueEventIds`, or both. The request accepts up to 10 ids total, and `limit` is capped at 5 articles per result. Use `customQuery` only when you want to bias the search toward a user-selected topic. Use `tbs` only when you need to override the time window for a dedicated experience, such as "past 24 hours". ## Integration notes - Feed endpoints are cached for 60 seconds per request and app scope. Do not poll more frequently unless the user explicitly refreshes. - On-demand market-news requests accept up to 10 ids total across `venueMarketIds` and `venueEventIds`. - `limit` is capped at 5 articles per market-news result and 50 rows for feed pages. - `relevanceScore` is a ranking signal within the response, not an absolute quality score across unrelated markets or categories. - News summaries explain why an article may matter to a market; they are not a replacement for the linked source article. ## Response fields to render | Field | Render it as | | --- | --- | | `result.question` | The market question the articles relate to. | | `result.eventTitle` | Optional event context above the market question. | | `article.title` | The article headline. | | `article.source` | Publisher/source label. | | `article.publishedAt` | Timestamp or recency label. | | `article.url` | External link to the original article. | | `article.summary` | Short explanation of why the article matters for the market. | | `article.relevanceScore` | Sort or filter signal within this response. | ## Render recommendations Show `source`, `publishedAt`, and `url` with each article so users can inspect the original source. Treat `summary` as market-context copy: it explains why the article may matter to the linked market, not a replacement for the article itself. `relevanceScore` is a relative ranking signal. Use it to order or hide low-confidence links inside a single response, but do not compare scores across unrelated pages as an absolute measure. ## Error handling | Status | Handle it as | | --- | --- | | `400` | The category, ids, or query options are invalid. Fix the request before retrying. | | `401` / `403` | The app header is missing or not allowed for the endpoint. | | `429` | The on-demand market-news request limit was reached. Back off and retry later. | If a category is disabled for your app, feed endpoints return an empty page with `data: []`, `nextCursor: null`, and `hasMore: false`. ## FAQ ### Is News Feed just a list of article links? No. News Feed links articles to specific prediction markets and includes market-impact summaries so apps can show why a story may matter to a tradeable market. ### Should I use article-first or market-first feeds? Use article-first feeds when the news story is the main object, such as a homepage or discovery rail. Use market-first feeds when the market is the main object, such as a market page, event page, or category page built around trading opportunities. ### Can agents use News Feed? Yes. Agents can use News Feed as structured market context: article metadata, market ids, summaries, relevance scores, and live linked-market prices are returned in API responses. ## Related View schemas and try the News Feed endpoints. Compose Discovery endpoints into category pages, market details, and event grids.