---
title: "Paginated episode metadata"
method: GET
path: "/api/v1/episodes"
---

# Paginated episode metadata

`GET /api/v1/episodes`

## Request

- Base URL: `https://bidclub.ai`
- URL: `https://bidclub.ai/api/v1/episodes`
- Auth: none declared

Newest-first metadata without the long Markdown bodies. Follow pagination.next_offset until it is null.

## Query parameters

- `show` string
- `lang` 'EN' | 'ZH'
- `limit` integer
- `offset` integer
- `asset` string
- `sector` string
- `focus` string

## Response `200`

One page of metadata.

- EpisodeListResponse
  - `episodes` EpisodeListItem[], required
    - `slug` string, required: Stable public identifier.
    - `show_id` string, required: Foreign key into /api/v1/shows.
    - `title` string, required: Complete canonical publisher title.
    - `display_title` string, nullable: Feed-only compression of an overlength title; null when unneeded.
    - `title_orig` string, nullable: Source-platform title when it differs.
    - `dek` string, nullable: One-line editorial standfirst.
    - `lang` 'EN' | 'ZH' | 'null', nullable: Language of the primary editorial fields.
    - `date` string, nullable: Publication calendar date, YYYY-MM-DD.
    - `published_at` string, nullable: Exact publication timestamp (RFC 3339); null for date-only archives.
    - `duration_min` number, nullable: Episode length in minutes.
    - `source_url` string, nullable
    - `source_label` string, nullable
    - `rss_url` string, nullable
    - `youtube_id` string, nullable
    - `youtube_url` string, nullable
    - `provenance` array[]: Ordered [stage, tool] pairs recording how the episode was produced.
      - string[]
    - `chips` string[]: Participant tags, each prefixed "person:" (e.g. "person:Jensen Huang").
    - `tag_assets` string[]: Zero to two closed asset taxonomy ids, primary first. Empty is valid even after classification.
    - `tag_sectors` string[]: Zero to two closed sector taxonomy ids, primary first. Empty is valid even after classification.
    - `tag_focus` string[]: Zero to two closed editorial-focus taxonomy ids, primary first. Empty is valid even after classification.
    - `tagging_status` 'pending' | 'classified' | 'failed' | 'skipped': Classification state. Non-classified episodes have empty tag arrays; classified does not require a tag in every facet.
    - `tagging_version` string, nullable: Taxonomy version used for classification; nonblank when tagging_status is classified, otherwise it may be null.
    - `shows` object, nullable
      - `name` string
  - `pagination` Pagination, required
    - `limit` integer, required
    - `offset` integer, required
    - `next_offset` integer, nullable, required: Offset of the next page, or null on the final page.
  - `artifacts` string, required: Constant hint string naming the per-episode JSON and file routes.

## Other responses

- `400`: invalid limit | invalid offset | invalid show | invalid lang | invalid {asset|sector|focus} tag: {id}
- `502`: Upstream database unavailable. Body: {"error": "upstream unavailable"}.

---

[API](https://skmtc.dev/bidclub/apis/bidclub-open-podcast-transcript-api.md) · [All operations](https://skmtc.dev/bidclub/apis/bidclub-open-podcast-transcript-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bidclub/apis/bidclub-open-podcast-transcript-api/revisions/a097c20ae335?raw)