Skip to main content
An empty data array is a 200, not an error, and it has three possible causes: the subject is not in the catalog, it is in the catalog but nothing names it, or a filter narrowed a real result to nothing. Each has a one-call check, and running them in order is faster than rephrasing. Every example below was run against https://api.particle.pro.

​
1. Confirm the subject is in the catalog, and read its mention count

Resolve the name before anything else. GET /v1/entities/search?q= matches people, companies, and other entities by name, nickname, ticker, handle, or domain, and every result carries match_quality and mentions.podcast_episodes, the number of episodes tagged with the subject. Ask for a few candidates: take the top hit on its own only when its match_quality is exact; otherwise read the descriptions and counts and choose, as here, where the strongest match is not the exact one.
Response (truncated)
Compare a company that resolves but has not come up on air yet:
Response (truncated)
A podcast_episodes of zero means no episode carries an entity tag for the subject. For a knowledge_graph_entity result, or a company result with a slug (the slug is its linked knowledge-graph entity), that settles it: a mentions or search call will be empty whatever the filters, and the right move is to watch for it with an alert rather than to keep querying. For a person, or a company without a slug, GET /v1/podcasts/mentions also scans dialogue for the name verbatim and marks such pages matched_by: "name", so make the unfiltered call in step 2 once before concluding. A name that returns no result at all is not in the knowledge graph yet. Use the handle from the response: a person or knowledge_graph_entity result’s slug, and for a company its id or domain as company_id (a company carries a slug only when it is linked to a knowledge-graph entity). Slugs are short handles Particle assigns, not names slugified (20VC is the-twenty-minute-vc, Lenny’s Podcast is lennys), a constructed slug returns 404, and a podcast slug is not an episode id. For shows, resolve with GET /v1/podcasts/search?q=; for companies by ticker, domain, or CIK, GET /v1/companies.

​
2. Confirm it has what you are asking for, before you narrow

Ask the broad question first. For “what has been said about X”, that is mentions with no filters but the subject:
For “how much, and when”, the timeseries answers in one call and shows which periods have volume, so you can pick a window that contains data:
The response carries total_mentions, total_episodes, and distinct_podcasts for the window, and a bucket per month; the first non-zero bucket is how far back the catalog names the subject. The catalog’s episodes go back to 2017, so a window that ends before then is empty for everyone.

​
3. Narrow one filter at a time

Add podcast_id, role, language, since, or until one at a time, and keep the last version that still returned data. On GET /v1/podcasts/episodes/search an empty first page usually carries a diagnostics block that names the filter responsible and gives the exact retry_with change; on the other list endpoints, the one-at-a-time walk is the equivalent. Two habits keep this step short:
  • A name is not a topic. semantic_search finds dialogue about an idea; a person’s or company’s name belongs in entity_id or company_id on GET /v1/podcasts/mentions, or as a filter on search. Putting “CoreWeave” in semantic_search finds segments that are semantically about a phrase, which is rarely the mentions you want.
  • Omit what you do not need. A placeholder such as x, -, or __omit__ is a real filter value; it fails validation or matches nothing.
  • Mentions for the filters and the empty-results checklist on that endpoint
  • Episode search for diagnostics and search modes
  • Coverage for what the catalog holds and how fresh it is