API FAQ: keys, errors, pagination, updates

Access and keys

How do I get an API key?

Request access and tell us which data you need. Each key is enabled for specific endpoints, and you can ask to add endpoints to an existing key.

How do I authenticate?

Send the key in the X-API-key header with every request to https://subalytics.com/api/v1/. See authentication.

Does my key include company mentions?

Not automatically. Entity mentions is a separate product with its own access: keys for other endpoints don't include the entity-* endpoints, and the reverse. See about entity mentions.

Which podcasts can I query?

Podcast endpoints return only the podcasts your key includes, with their episodes and transcripts.

Errors

Why do I get 401 Unauthorized?

The API key is missing, or it isn't enabled for the endpoint you called.

Why do I get 403 Forbidden?

The request names a podcast, by sub_id, or one of its episodes, by episode_sub_id, that your key doesn't include.

Why do I get 400 "Unknown parameters"?

Any query parameter not listed for an endpoint is rejected with 400, so check the spelling against the endpoint's page. Invalid dates, date ranges, limits, cursors and min_confidence values also return 400, and the message says which.

What should I do about a 500 error?

Something went wrong on our side. Retry later, and check the API status page.

Is an empty result an error?

No. An empty results list is a successful response.

Pagination and dates

How many results can I get per request?

limit defaults to 25, with a maximum of 100. Full podcast transcripts (full=true) default to 10, with a maximum of 10, because one transcript can be 1–2 MB.

How do I page through results?

Cursor endpoints return next_cursor: pass it back as cursor until it is null. Offset endpoints take offset. Each endpoint's page says which it uses. See pagination.

What time zone and format are dates in?

UTC, as YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS. Podcast and entity mentions responses return ISO 8601 with a Z suffix, the same format the filters accept. See date filters.

Do paths need a trailing slash?

Yes. Every endpoint path ends with /, for example /api/v1/podcasts/.

Updates and syncing

How often is the data updated?

• Creators: a weekly snapshot of each creator.
• Podcasts: new episodes are transcribed in a daily run at 05:00 UTC.
• Company mentions: Bluesky posts usually appear within minutes, Substack posts after each collection run, and podcast episodes within a few hours of the daily run.

How do I keep my copy in sync?

Ask only for what changed since your last sync with updated_from (and, for episodes, transcribed_from). Start each sync a few minutes before the previous one; receiving the same record twice is harmless. See the daily podcast sync guide.

Can a transcript change after it is published?

Yes, for example when speaker names are filled in later. Its updated_at changes, so an updated_from sync picks it up again.

Can a company mention disappear?

Yes. Past content is re-checked as matching improves, which can add, change or remove mentions. Removals don't show up in an updated_from sync, so re-pull a recent window (e.g. the last 30 days) periodically if you need an exact match.

Are speaker names always available?

No. Speaker identification is automatic and best-effort: any of name, role, title and company may be null. See podcast transcripts.

Tools

Is there an OpenAPI spec?

Yes, an OpenAPI 3.1 description is at /openapi.json, for API clients, code generators and AI tools.

Can I read the docs as Markdown?

Yes. Add .md to any docs page, for example /docs/podcast-transcripts.md, or get every page in one file at /llms-full.txt.

Can I check whether the API is up?

Yes. See API status, or call GET /api/status/, which returns {"status": "live"} and needs no key.