---
title: "List story clusters"
method: GET
path: "/api/stories"
---

# List story clusters

`GET /api/stories`

## Request

- Base URL: `https://techsnif.com`
- URL: `https://techsnif.com/api/stories`
- Auth: none declared

Story clusters with flexible sorting, filtering, and offset pagination. Returns real total counts.

## Query parameters

- `limit` integer
- `offset` integer
- `sort` 'rank' | 'newest'
- `tier` integer
- `publisher` string
- `platform` 'x' | 'bluesky' | 'linkedin' | 'forums' | 'hn' | 'threads' | 'mastodon' | 'other'
- `has_discussion` 'true'
- `since` string, date-time
- `until` string, date-time
- `topic` string
- `entity` string

## Response `200`

Story cluster list

- StoryListResponse
  - `stories` StoryCluster[]
    - `id` string
    - `slug` string
    - `headline` string
    - `excerpt` string
    - `whyItMatters` string: AI-generated 2-3 sentence context blurb (top stories only)
    - `topics` string[]
    - `rank` integer
    - `headlineTier` integer: 1=standard, 2=major, 3=top story
    - `leadUrl` string, uri
    - `leadTitle` string
    - `sourcePublisher` string
    - `sourceAuthor` string
    - `imageUrl` string, uri
    - `publishedAt` string, date-time
    - `firstSeenAt` string, date-time
    - `lastSeenAt` string, date-time
    - `xPostUrl` string, uri
    - `links` object[]
      - `id` string
      - `title` string
      - `url` string, uri
      - `publisher` string
      - `author` string
      - `linkType` 'lead' | 'sub' | 'more' | 'related'
      - `position` integer
    - `commentaryLinks` object[]
      - `id` string
      - `platform` string
      - `label` string
      - `url` string, uri
      - `position` integer
    - `techsnifArticle` object
      - `slug` string
      - `title` string
      - `publishedAt` string, date-time
  - `total` integer: Total matching clusters (for pagination)
  - `limit` integer
  - `offset` integer

## Other responses

- `400`: Invalid request parameters

---

[API](https://skmtc.dev/techsnif/apis/techsnif-api.md) · [All operations](https://skmtc.dev/techsnif/apis/techsnif-api/llms.txt) · [OpenAPI document](https://skmtc.dev/techsnif/apis/techsnif-api/revisions/7404c46acbb0?raw)