> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# From an empty page to the data

> Three checks that turn an empty data array into the call that returns what you were looking for: confirm the subject is in the catalog, confirm it has dialogue, then narrow one filter at a time.

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.

```bash theme={"dark"}
curl "https://api.particle.pro/v1/entities/search?q=altman&limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    {
      "type": "person",
      "match_quality": "strong",
      "mentions": { "podcast_episodes": 12354, "news_articles": 53563 },
      "person": { "id": "2hMiAB3dLWfVEVI9JdgXVo", "slug": "sam-altman", "name": "Sam Altman", "description": "CEO of OpenAI, American entrepreneur who co-founded the AI company and oversaw the launch of ChatGPT in 2022." }
    },
    {
      "type": "person",
      "match_quality": "exact",
      "mentions": { "podcast_episodes": 52, "news_articles": 8 },
      "person": { "id": "5a19wkwZOJeUH7KT0OGcPi", "slug": "russ-altman", "name": "Russ Altman", "description": "Professor of bioengineering at Stanford; host of \"The Future of Everything\" podcast" }
    }
    // …
  ],
  "has_more": true
}
```

Compare a company that resolves but has not come up on air yet:

```bash theme={"dark"}
curl "https://api.particle.pro/v1/entities/search?q=firecrawl&limit=1" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    {
      "type": "company",
      "match_quality": "exact",
      "mentions": { "podcast_episodes": 0, "news_articles": 0 },
      "company": { "id": "3y1SVPZ0SiSuUYuM7YWbuJ", "slug": "firecrawl-corporation", "name": "Firecrawl", "domain": "firecrawl.dev" }
    }
  ]
}
```

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](/alerts/overview) rather than to keep querying. For a `person`, or a `company` without a `slug`, [`GET /v1/podcasts/mentions`](/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=`](/podcasts/search); for companies by ticker, domain, or CIK, [`GET /v1/companies`](/companies/overview).

## 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:

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/mentions?entity_id=sam-altman&limit=1" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

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:

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/mentions/timeseries?entity_id=sam-altman&interval=month" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

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`](/podcasts/episode-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`](/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.

## Related

* [Mentions](/podcasts/mentions) for the filters and the empty-results checklist on that endpoint
* [Episode search](/podcasts/episode-search) for `diagnostics` and search modes
* [Coverage](/coverage) for what the catalog holds and how fresh it is