Pagination & idempotency

List endpoints (/channel, /playlist, /search) return up to limit videos per page (1–50, default 5) plus a next_cursor. When next_cursor is non-null, pass it back as cursor to fetch the next page; null means the list is exhausted. Each page is one successful response and costs 1 credit.

# Fetch the next page by echoing next_cursor back as cursor
POST /api/v1/transcripts/search
{ "query": "lex fridman", "limit": 10, "cursor": "eyJvIjoxMH0" }

Because requests are billed, retry safely by sending an Idempotency-Key header (any unique string, ≤255 chars). The first request runs and is charged; retries with the same key replay the stored response — same body, no extra charge — and carry an Idempotent-Replayed: true header. Replays are kept for 24 hours.

curl https://transcriptfetch.com/api/v1/transcripts/video \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c-7b2e-...-a3" \
  -d '{"video":"dQw4w9WgXcQ"}'