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

# Entities

> People, organizations, places, and concepts — the connective tissue across audio and structured data.

Entities are the knowledge-graph layer that connects everything else. The same entity (Sam Altman, Nvidia, Federal Reserve) appears as a speaker on episodes, as a mention in transcripts, as a sponsor in advertising data, and as the linked identity on a company profile. Resolve once, then follow the entity across the platform.

Each entity has a stable `slug` (e.g. `sam-altman`, `nvidia`, `kara-swisher`) and a canonical `id`. Either is accepted anywhere an entity reference is needed.

<Note>Available to MCP agents as [`particle_entity_resolve`](/mcp/tools/people/entity-resolve) (the union resolver) and [`particle_person_resolve`](/mcp/tools/people/person-resolve) (people only).</Note>

## Search entities

Search across people, companies, and knowledge graph entities in one ranked call. Pass a name, partial name, nickname, stock ticker, `@handle`, or website domain. Each result carries a `type` (`person`, `company`, or `knowledge_graph_entity`) telling you which collection it belongs to, and a `match_quality` so you can tell an exact identification from a fuzzy guess.

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

  ```js JavaScript theme={"dark"}
  const res = await fetch(
    "https://api.particle.pro/v1/entities/search?q=Sam+Altman&limit=3",
    { headers: { "X-API-Key": process.env.PARTICLE_API_KEY } },
  );
  const { data } = await res.json();
  ```

  ```python Python theme={"dark"}
  res = httpx.get(
      "https://api.particle.pro/v1/entities/search",
      params={"q": "Sam Altman", "limit": 3},
      headers={"X-API-Key": os.environ["PARTICLE_API_KEY"]},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

Each result is a discriminated union: `type` says which kind it is, and exactly one of `person`, `company`, or `knowledge_graph_entity` holds the matched record — the same compact object shape those resources return elsewhere, so you can reuse your existing rendering. `match_quality` and `mentions` (where the entity shows up) sit alongside it.

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    {
      "type": "person",
      "match_quality": "exact",
      "mentions": { "podcast_episodes": 6254, "news_articles": 18230 },
      "person": {
        "id": "17PzxG1t12xzno",
        "slug": "sam-altman",
        "name": "Sam Altman",
        "description": "CEO of OpenAI"
      }
    },
    {
      "type": "company",
      "match_quality": "exact",
      "mentions": { "podcast_episodes": 12718, "news_articles": 8400 },
      "company": {
        "id": "1aB2c…",
        "slug": "nvidia",
        "name": "Nvidia",
        "domain": "nvidia.com",
        "ticker": "NVDA"
      }
    }
  ],
  "has_more": false
}
```

Take the embedded record's `id` (or `slug`) to the matching resource endpoint (`/v1/people`, `/v1/companies`, `/v1/entities`), or its `id` to alert creation.

### Search parameters

| Parameter | Description                                                                            |
| --------- | -------------------------------------------------------------------------------------- |
| `q`       | Free-text query: name, partial name, nickname, ticker, `@handle`, or domain (required) |
| `type`    | Restrict to one kind: `person`, `company`, or `knowledge_graph_entity`                 |
| `limit`   | Results per page (default 25, max 100)                                                 |
| `cursor`  | Pagination cursor from the previous response's `cursor`, to fetch the next page        |

## List entities

`GET /v1/entities` returns the most-mentioned knowledge graph entities, or a filtered slice. (To search by name, use `/v1/entities/search` above.)

| Parameter    | Description                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------- |
| `type`       | Restrict to an entity category (e.g. `person`, `company`); see `GET /v1/entities/types` for the slugs |
| `podcast_id` | Restrict to entities appearing in a specific podcast                                                  |
| `ids`        | Bulk multi-get: fetch a known set of entities by slug or ID in one call (see below)                   |

## Get a single entity

```bash theme={"dark"}
# Either of these resolves to Sam Altman
curl "https://api.particle.pro/v1/entities/sam-altman" \
  -H "X-API-Key: $PARTICLE_API_KEY"
curl "https://api.particle.pro/v1/entities/17PzxG1t12xzno" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response theme={"dark"}
{
  "id": "17PzxG1t12xzno",
  "slug": "sam-altman",
  "name": "Sam Altman",
  "description": "CEO of OpenAI",
  "wikipedia_url": "https://en.wikipedia.org/wiki/Sam_Altman",
  "image_url": "https://cdn.particle.pro/url/media/kge/m/02kx06l/…"
}
```

## Fetch many at once

When you already hold a set of entity slugs or IDs, pass them as a comma-separated `ids` list to fetch them all in a single request instead of one call per entity — up to 100 per call. Entities come back in the same shape as search and in the order you asked for them. A ref that doesn't resolve is simply left out (no error, no placeholder), so compare the returned `slug`/`id` values against what you sent to find any that are missing.

```bash theme={"dark"}
curl "https://api.particle.pro/v1/entities?ids=sam-altman,nvidia,17PzxG1t12xzno" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    { "id": "17PzxG1t12xzno", "slug": "sam-altman", "name": "Sam Altman" },
    { "id": "2dFq…", "slug": "nvidia", "name": "Nvidia" }
  ],
  "has_more": false
}
```

When `ids` is present the other filters (`q`, `type`, `podcast_id`) and pagination are ignored — it is a direct multi-get of exactly the refs you supply.

## Podcast appearances

To find every podcast episode where an entity has been featured or discussed across the catalog, use [`list-episodes`](/podcasts/episodes#list-episodes) with an `entity_id` filter. Add a `role` filter to narrow to `guest`, `host`, `panelist`, `correspondent`, or `mention`.

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

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    {
      "id": "78cgekLUjCJBUZbj3s5K8Y",
      "title": "WHCD Shooting Aftermath, Musk and Altman Face-Off, Spirit Airlines Bailout",
      "podcast": { "id": "QpMz7GYKfSNuUa6zKXA4Q", "title": "Pivot" },
      "published_at": "2026-04-28T10:00:00Z",
      "duration_seconds": 4206,
      "has_transcript": true,
      "segment_count": 21,
      "clip_count": 8,
      "entity_count": 146,
      "speakers": [ /* … */ ]
    }
    // …
  ],
  "has_more": true,
  "cursor": "…"
}
```

Add `role=guest` to limit results to episodes where the entity was actually a guest, rather than every episode that happens to mention them.

## A typical cross-referencing flow

<Steps>
  <Step title="Resolve the entity">
    Look up by name with [`/v1/entities/search`](#search-entities) or use a slug you already have.

    ```bash theme={"dark"}
    curl ".../v1/entities/sam-altman"
    ```
  </Step>

  <Step title="Find episodes">
    Use the slug as `entity_id` on episodes or clips.

    ```bash theme={"dark"}
    curl ".../v1/podcasts/episodes?entity_id=sam-altman&limit=10"
    ```
  </Step>

  <Step title="Drill into one episode">
    Pull the dialogue lines around mentions, or the highlight clips.

    ```bash theme={"dark"}
    curl ".../v1/podcasts/episodes/{id}/transcript/mentions?entity_id=sam-altman"
    curl ".../v1/podcasts/episodes/{id}/clips"
    ```
  </Step>

  <Step title="Cross to companies">
    Many entities are also linked to companies. Lookup by `entity_id` on the companies endpoint.

    ```bash theme={"dark"}
    curl ".../v1/companies?entity_id=nvidia"
    ```
  </Step>
</Steps>

The [Quickstart](/quickstart) walks the full flow end-to-end.

## Related

* [Topics](/knowledge-graph/topics) — taxonomy companion to entities
* [Companies → Overview](/companies/overview) — entities linked to company records
* [Transcripts → Mentions](/podcasts/transcripts#transcript-mentions) — dialogue around entity mentions
* [Concepts → IDs and slugs](/concepts#ids-and-slugs) — slug resolution rules