---
title: "Top stories (last 48h)"
method: GET
path: "/api/stories/top/"
tags: ["stories"]
---

# Top stories (last 48h)

`GET /api/stories/top/`

## Request

- Base URL: `https://api.alphai.io`
- URL: `https://api.alphai.io/api/stories/top/`
- Auth: HTTP bearer

The strongest stories of the trailing 48 hours, ranked: a story's
`importance` plus a coverage bonus of `min(3, log2(publishers))`,
minus one point per 12 hours since its key facts last changed
(`updated_at`). One slot per ticker and two per no-ticker macro
category, so one event cannot fill the list. Only stories with a
published summary and `importance >= 7` qualify. Fixed size of up to
50, no pagination; `ranking_version` names the formula so a change
is visible, `as_of` is when the list was ranked.

Compared with `/api/news/trending/`: trending ranks single articles
and collapses reprints; this ranks the stories themselves (two or
more publishers), each with an AlphAI-written summary. A story's
`story_id` is the same key an article row carries, so a trending
item's `story_id` opens the story here.

## Response `200`

Ranked stories, strongest first.

- TopStories
  - `results` StoryCard[], required
    - `story_id` string, required: Permanent story key — the `uid` of the story's first root article; the same value article rows carry in their `story_id`. Opens `/api/stories/{story_id}/`.
    - `title` string, required: The summary's headline, written by AlphAI from the articles. In `preparing` state, the lead article's own headline.
    - `summary` string, required: One paragraph: what happened, with the figures. In `preparing` state, the lead article's collector summary.
    - `importance` integer, required: How much the event matters, on the feed's 1-10 relevance scale: the median of each publisher's best-scored article on the event, rounded down — so one outlet's 9 does not lift a story every other outlet scored 7. Stories below 7 are not listed and carry no summary.
    - `category` string, required: The feed category of the story's root article (same 14 values as `enrichment.category`).
    - `tickers` string[], required: Active tickers the story's articles are tagged with. Macro stories carry an empty list.
    - `publishers` integer, required: Distinct publishers (source domains) covering the story — always 2 or more.
    - `materials` integer, required: Articles in the story that the feed shows (`relevance_score >= 4`), reprints included.
    - `first_published_at` string, date-time, nullable, required: Publication time of the story's earliest article.
    - `last_material_at` string, date-time, nullable, required: Publication time of the story's latest article; `/api/stories/` is ordered by it.
    - `updated_at` string, date-time, nullable, required: When the story's key facts last changed — a rewrite that only reworded the summary does not move it. The freshness Top stories rank by.
    - `summary_state` 'published' | 'stale' | 'preparing', required: `published`: the summary covers every article the story had when it was written. `stale`: articles joined since; the rewrite is queued. `preparing`: no summary yet — the texts are the lead article's own.
  - `as_of` string, date-time, required: When the list was ranked.
  - `ranking_version` integer, required: The ranking formula's version; a change to the formula increments it.

## Other responses

- `401`: Missing or invalid API key.
- `404`: The Stories section is switched off.
- `429`: Rate limit exceeded — either the per-minute burst cap or the per-day volume cap. The `Retry-After` header is the earliest second a retry can succeed, not a guess (a burst block is short, ≤60s; a day-cap block is capped at 3600s — the true reset is `X-RateLimit-Reset`). The `X-RateLimit-*` trio shows the daily volume budget. The body's `extra` names your tier, its `limit_per_minute` / `limit_per_day`, `retry_after_seconds`, and — below Pro — an `upgrade` block with the higher tiers' caps and the pricing URL. A rejected request does not itself consume quota, so retrying after `Retry-After` costs you nothing extra.

## Changes

- **2026-10-09** `8cf7aaea97e3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/alphai/apis/alphai-rest-api/changes/api/stories/top/get.md)

---

[API](https://skmtc.dev/alphai/apis/alphai-rest-api.md) - [All operations](https://skmtc.dev/alphai/apis/alphai-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/alphai/apis/alphai-rest-api/revisions/7a88b559ccfa?raw)