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

# Search

> Find a podcast by name. Forgiving, typo-tolerant ranked search over the catalog, with a match_quality signal on every result.

`GET /v1/podcasts/search` finds *podcasts* (shows) by name. It is the canonical way to search the catalog: pass `q` and get back a ranked, paginated list of podcast objects — the same `PageResponse<Podcast>` envelope used by every list endpoint.

<Warning>
  **Breaking change (June 2026):** this endpoint previously searched episode
  *dialogue*. That capability now lives at
  [`GET /v1/podcasts/episodes/search`](/podcasts/episode-search). Sending
  `semantic_search` or `keyword_search` here now returns `422` with a message
  pointing at the episode-search endpoint — they are no longer silently
  ignored. Migrate those calls to `/v1/podcasts/episodes/search`; the
  parameters and response shape are unchanged on the new path.
</Warning>

## Searching by name

The search is forgiving. It handles typos, missing or extra words (`offline jon favreau` finds *Offline with Jon Favreau*), a name plus qualifiers (`equity techcrunch`), and pasted episode titles (`Ferrari | Acquired` finds *Acquired*):

```bash theme={"dark"}
curl --get "https://api.particle.pro/v1/podcasts/search" \
  --data-urlencode "q=hard fork" \
  --data-urlencode "limit=3" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

The best matches come first, and each result carries a `match_quality` field telling you how confident the match is.

<Note>
  `GET /v1/podcasts?q=…` accepts the same parameters and returns the same
  results — it remains supported for backwards compatibility, but prefer
  `/v1/podcasts/search` in new integrations.
</Note>

## `match_quality` — how confident is each result

When `q` is provided, every result includes `match_quality`, strongest first:

| Value         | Meaning                                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exact`       | This is the show with that name.                                                                                                                              |
| `partial`     | The name matches your search strongly — your search may have included extra words.                                                                            |
| `fuzzy`       | The name is similar but not the same. It may be the show you meant with a typo, or a different show with a near-identical name — verify before relying on it. |
| `description` | Your search text appears in the show's description rather than its name.                                                                                      |
| `speculative` | A loose suggestion, listed last.                                                                                                                              |

When resolving a show programmatically, act on `exact` or `partial` results and treat anything weaker as candidates to confirm.

`q=` is a *ranked text search*, not a deterministic mapping: the top hit is usually right but isn't guaranteed to be. If you already hold a platform-native identifier (Apple, Spotify, YouTube, an RSS feed URL, …), use [`GET /v1/podcasts/lookup`](/podcasts/lookup) for a deterministic answer instead.

## Combining search with filters

`/v1/podcasts/search` accepts every filter the [list endpoint](/podcasts/overview) does — `topic_id`, `language`, `suitability_tier`, `popularity_threshold`, and the [format filters](/podcasts/format) (`guest_frequency`, `format_signal`, `has_ads`, `has_video`, episode length and cadence bounds):

```bash theme={"dark"}
curl --get "https://api.particle.pro/v1/podcasts/search" \
  --data-urlencode "q=daily news" \
  --data-urlencode "language=en" \
  --data-urlencode "suitability_tier=SAFE" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

When `q` is combined with other filters, text relevance drives the ordering — `q` is the more explicit statement of intent. Omit `q` entirely and the endpoint behaves as a filtered catalog listing.

## Response

A paginated list of podcast objects:

```json theme={"dark"}
{
  "data": [
    {
      "id": "QpMz7GYKfSNuUa6zKXA4Q",
      "title": "Hard Fork",
      "slug": "hard-fork",
      "language": "en",
      "match_quality": "exact",
      "episode_count": 142,
      "speakers": [
        { "name": "Kevin Roose", "role": "HOST", "entity_slug": "kevin-roose" },
        { "name": "Casey Newton", "role": "HOST", "entity_slug": "casey-newton" }
      ]
    }
  ],
  "has_more": true,
  "cursor": "…"
}
```

Each result's `slug` is the stable handle for every other podcast endpoint — episodes, transcripts, bias, suitability, advertising, and more. See the [Podcasts overview](/podcasts/overview) for the full object shape.

## Pagination

Standard `limit` (1–100, default 25) + opaque `cursor`. Pass the `cursor` from the previous response back as `?cursor=…` to fetch the next page.

## Related

* [Episode search](/podcasts/episode-search) — search *inside* episode dialogue by meaning or exact phrase.
* [Lookup by external ID](/podcasts/lookup) — deterministic resolution from Apple, Spotify, YouTube, and other platform identifiers.
* [Podcasts overview](/podcasts/overview) — the full podcast object, detail endpoints, and discovery filters.
* [Mentions](/podcasts/mentions) — every dialogue line where a person or company is named.