| Identifiers | Podcast, episode, publisher, company, person, entity, and topic {id} parameters accept the canonical id or the slug; everything else (segments, clips, alerts, matches, deliveries, connections) takes the id a response returned. Podcast ids also accept a numeric Apple collection id; company ids also accept a domain. Slugs are short handles Particle assigns, not names slugified: 20VC is the-twenty-minute-vc, Lenny’s Podcast is lennys, All-In is all-in. Take them from responses; a constructed slug returns 404, and trying other spellings never resolves it. A podcast slug is not an episode id: list the show’s episodes to get one. Resolve free text with GET /v1/entities/search?q=, GET /v1/podcasts/search?q=, and GET /v1/companies?q=; resolve platform ids (Apple, Spotify, YouTube, RSS feed URLs, episode guids) with GET /v1/podcasts/lookup and GET /v1/podcasts/episodes/lookup. |
| Optional parameters | Omit a parameter you do not need. A placeholder value (x, -, __omit__) is a real filter value and either fails validation or matches nothing. Each concept has one parameter name; q is the free-text query wherever one exists. |
| Retries | Read error_code before retrying. A 429 carries Retry-After; wait that long. Back off exponentially on a 5xx. Never resend a 4xx unchanged: a 422 names the parameter or endpoint to fix, a 404 on a slug means resolve it again, and a 402 other than payment_required names a billing state that a retry cannot change. See Handle errors and retries. |
| Pagination | List responses are {data, has_more, cursor}. Pass cursor back to continue; limit is usually 1 to 100 with a default of 25, and cursor is absent on the last page. Some lists cap lower (a company’s advertised podcasts at 24) and some episode sub-resources return everything when limit is omitted. Cursors are opaque and specific to the endpoint that issued them. |
| Expansion | Detail responses are lean; include= adds sections (an episode’s segments, clips, transcript, topics, entities; a company’s people, products, competitors; a podcast’s related). |
| Time | Timestamps are ISO 8601 in UTC. Positions inside audio are decimal seconds (start_seconds, end_seconds). Date filters (since, until, published_after, published_before) usually accept a date or a timestamp, with a bare date covering the whole day; a few analytics endpoints, such as publisher bias, require a full timestamp, and their schema says so. |
| Language | language is an ISO 639-1 code matched on the primary subtag: fr covers fr-CA. |
| Rate limit | 10,000 requests per minute per organization, shared across its keys and projects. X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset accompany rate-limited responses; a 429 (rate_limit_exceeded) carries Retry-After. |
| Errors | RFC 9457 application/problem+json with a stable error_code and, when there is a self-service fix, a resolve object. A missing, mistyped, revoked, or expired key returns 401 api_key_required. See the error catalog. |
| Metering | Each request is one metered unit; the free endpoints (/v1/podcasts/stats, /v1/embed/*) cost nothing. Every response carries X-Trace-ID; quote it when contacting support. |
| Compatibility | The API grows additively under /v1: new fields, parameters, and endpoints never break an existing call. Breaking changes are announced ahead of time in the changelog. |
