> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agg.market/llms.txt
> Use this file to discover all available pages before exploring further.

# News Feed

> Integrate market-aware news feeds into partner discovery and market detail experiences

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:

<ParamField header="x-app-id" type="string" required>
  Your AGG app identifier.
</ParamField>

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/listfeeds)            | You want the available feed categories and item counts.                          |
| [Get article feed](/api-reference/discovery/getarticlefeed) | You want an article-first feed with linked markets for each article.             |
| [Get market feed](/api-reference/discovery/getmarketfeed)   | You want a market-first feed where each market includes recent related articles. |
| [Get market news](/api-reference/discovery/getmarketnews)   | 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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/getmarketnews).

## 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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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/getmarketnews).

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

<CardGroup cols={2}>
  <Card title="API Reference" icon="book-open" href="/api-reference/discovery">
    View schemas and try the News Feed endpoints.
  </Card>

  <Card title="Building Market Views" icon="layer-group" href="/recipes/building-market-views">
    Compose Discovery endpoints into category pages, market details, and event grids.
  </Card>
</CardGroup>