Search Episodes
https://api.podengine.ai/api/v1/search/episodes Search for episodes by title, description, or transcript text, with optional filters on guest, host, and sponsor names
Request
Request body
Search terms1
searchTermsarray of object4 fields
Terms to search for in the episode title, the episode description, the transcript, or the parent podcast's title and description.
The text to look for. Wrapping it in single or double quotes forces a phrase match, the same as setting searchTermOptions.phraseMatch.
How to match the term. 'text' runs keyword matching against each of the searchTargets. 'embeddings' is reserved for semantic search and is not accepted yet — a request using it is rejected.
Which fields to match this term against. A result matches if the term hits any one of its targets, so listing several widens the search rather than narrowing it.
searchTermOptionsobject4 fields
How this term is matched: whether it is required, treated as a phrase, or matched loosely.
How this term combines with the others. 'optional' (the default) lets the term raise a result's relevance without being required, though a result still has to match at least one term. 'must' requires it. 'not' excludes anything it matches.
Whether to match the search term as a phrase
How many words apart tokens can appear in a document to be considered a match
Whether to use fuzzy matching
Episode filters7
Restrict results to these specific episode IDs
Specific episode IDs to exclude from results
Only episodes published on or after this date (inclusive)
Only episodes published strictly before this date (exclusive). Combine with publishedSince for a bounded window, e.g. publishedSince=90 days ago + publishedBefore=30 days ago.
Only episodes whose Pod Engine record changed on or after this date. This tracks our record, not the show's own updates, so use it to pick up everything that has changed since your last sync.
Only episodes added to Pod Engine on or after this date. An episode is added when we first index it, which can be well after it was published — use publishedSince to filter on the publication date instead.
Filter to episodes that have a transcript (true) or that do not (false)
People & sponsors2
personFiltersarray of object6 fields
Filter episodes by the people on them. Entries are ANDed together, e.g. [{ "name": "Elon Musk", "type": "guest" }, { "name": "Joe Rogan", "type": "host" }] returns only episodes where Elon Musk appeared as a guest and Joe Rogan was a host. An entry with matchMode "not" instead excludes episodes featuring that person.
The name to match
'must' (default) only returns episodes matching this entry; 'not' excludes episodes matching this entry
Whether to match the name as a phrase (all words, in order). Defaults to true; set false for a loose per-word match.
How many words apart tokens can appear in a name to still count as a phrase match
Whether to tolerate close spellings. Uses per-word fuzzy matching with all words required, so it ignores word order and cannot be combined with slop.
sponsorFiltersarray of object5 fields
Filter episodes by sponsor / advertiser name. Entries are ANDed together; an entry with matchMode "not" instead excludes episodes with that sponsor.
The name to match
'must' (default) only returns episodes matching this entry; 'not' excludes episodes matching this entry
Whether to match the name as a phrase (all words, in order). Defaults to true; set false for a loose per-word match.
How many words apart tokens can appear in a name to still count as a phrase match
Whether to tolerate close spellings. Uses per-word fuzzy matching with all words required, so it ignores word order and cannot be combined with slop.
Podcast filters20
iTunes genres to include in results
iTunes genres to exclude from results
Specific podcast IDs to include in results
Specific podcast IDs to exclude from results
Filter podcasts by language
Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us
Filter podcasts founded after this date
Filter podcasts with episodes published after this date
Minimum number of total episodes
Maximum number of total episodes
Minimum iTunes rating score
Minimum number of iTunes ratings
Minimum Spotify rating score
Minimum number of Spotify ratings
Minimum number of Castbox plays
Minimum number of Castbox subscribers
Filter podcasts that have primary contact information
Filter podcasts with specific social media presence from beehiiv, behance, bluesky, discord, facebook, github, instagram, linkedin, linktree, mastodon, medium, patreon, pinterest, reddit, snapchat, soundcloud, substack, threads, tiktok, tumblr, twitch, twitter, vimeo, whatsapp, youtube
Filter podcasts that feature guests
Audience & scores2
podcastAuthorityScoreobject5 fields
Filter podcasts by their Authority Score
qualityScoreobject2 fields
Restrict results by the quality component of the Authority Score, which rates how well the show is produced and maintained: release consistency, episode length, artwork, show notes, transcript coverage, contact details and RSS completeness. Podcasts we have not scored are excluded.
engagementScoreobject2 fields
Restrict results by the engagement component of the Authority Score, which rates how strongly listeners respond to the show: review counts and ratings, recent Apple US chart position, and Castbox plays and subscribers. Podcasts we have not scored are excluded.
youtubeScoreobject2 fields
Restrict results by the YouTube component of the Authority Score, which rates the channel's subscribers, total views and most-viewed video. Podcasts we have not scored are excluded.
podcastAudienceEstimatedMonthlyListenersobject2 fields
Filter by the published podcast monthly audience estimate (audio downloads plus YouTube views over 30 days). Bounds are inclusive; omit min or max for an open-ended range. Podcasts without an estimate are excluded. Example: { "min": 10000, "max": 100000 }.
Transcript snippets3
Return the opening of each matching episode transcript alongside the result, as transcriptTextSnippet. Episodes with no transcript return null.
How many characters of the transcript includeTranscriptSnippet returns. Defaults to 500. This is the start of the transcript, not the part that matched — for the matching text, search the transcript target and read the highlights.
How many characters each highlighted transcript fragment contains when a search term targets the transcript. Defaults to 300.
Project2
projectobject6 fields
Details about any Project this search is associated with. If included will filter out podcasts related to the project.
The Pod Engine Project ID
If true, will not include any podcasts marked as ignored on this project in the results.
If true, will not include any podcasts on the project list in the results.
If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response
If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.
If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.
[DEPRECATED] Project ID to associate the search with
Sorting1
sortOrderarray of object3 fields
Specify how results should be sorted
What to order by. 'relevance' is the search score. 'recentActivity' is the episode's publication date when searching episodes, and the podcast's most recent episode date when searching podcasts. 'title' orders alphabetically. 'appleReviews' and 'spotifyReviews' order by a rating that weighs the number of reviews as well as the average, so a 5.0 from three listeners does not outrank a 4.7 from thousands.
Where results that have no value for this field go. Defaults to 'last'. Ignored for 'relevance', which every result has.
Pagination2
Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).
Number of results to return per page
Response
200 application/jsondataobjectrequired6 fields
searchOptionsobjectrequired40 fields
Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).
Number of results to return per page
projectobject6 fields
Details about any Project this search is associated with. If included will filter out podcasts related to the project.
The Pod Engine Project ID
If true, will not include any podcasts marked as ignored on this project in the results.
If true, will not include any podcasts on the project list in the results.
If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response
If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.
If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.
[DEPRECATED] Project ID to associate the search with
searchTermsarray of object4 fields
Terms to search for in the episode title, the episode description, the transcript, or the parent podcast's title and description.
The text to look for. Wrapping it in single or double quotes forces a phrase match, the same as setting searchTermOptions.phraseMatch.
How to match the term. 'text' runs keyword matching against each of the searchTargets. 'embeddings' is reserved for semantic search and is not accepted yet — a request using it is rejected.
Which fields to match this term against. A result matches if the term hits any one of its targets, so listing several widens the search rather than narrowing it.
searchTermOptionsobject4 fields
How this term is matched: whether it is required, treated as a phrase, or matched loosely.
How this term combines with the others. 'optional' (the default) lets the term raise a result's relevance without being required, though a result still has to match at least one term. 'must' requires it. 'not' excludes anything it matches.
Whether to match the search term as a phrase
How many words apart tokens can appear in a document to be considered a match
Whether to use fuzzy matching
iTunes genres to exclude from results
Specific podcast IDs to exclude from results
Specific episode IDs to exclude from results
Filter podcasts founded after this date
Filter podcasts that have primary contact information
Filter podcasts with specific social media presence from beehiiv, behance, bluesky, discord, facebook, github, instagram, linkedin, linktree, mastodon, medium, patreon, pinterest, reddit, snapchat, soundcloud, substack, threads, tiktok, tumblr, twitch, twitter, vimeo, whatsapp, youtube
iTunes genres to include in results
Specific podcast IDs to include in results
Filter podcasts by language
Filter podcasts with episodes published after this date
Maximum number of total episodes
Minimum number of Castbox plays
Minimum number of Castbox subscribers
Minimum iTunes rating score
Minimum number of iTunes ratings
Minimum Spotify rating score
Minimum number of Spotify ratings
Minimum number of total episodes
Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us
Filter podcasts that feature guests
podcastAuthorityScoreobject5 fields
Filter podcasts by their Authority Score
qualityScoreobject2 fields
Restrict results by the quality component of the Authority Score, which rates how well the show is produced and maintained: release consistency, episode length, artwork, show notes, transcript coverage, contact details and RSS completeness. Podcasts we have not scored are excluded.
engagementScoreobject2 fields
Restrict results by the engagement component of the Authority Score, which rates how strongly listeners respond to the show: review counts and ratings, recent Apple US chart position, and Castbox plays and subscribers. Podcasts we have not scored are excluded.
youtubeScoreobject2 fields
Restrict results by the YouTube component of the Authority Score, which rates the channel's subscribers, total views and most-viewed video. Podcasts we have not scored are excluded.
podcastAudienceEstimatedMonthlyListenersobject2 fields
Filter by the published podcast monthly audience estimate (audio downloads plus YouTube views over 30 days). Bounds are inclusive; omit min or max for an open-ended range. Podcasts without an estimate are excluded. Example: { "min": 10000, "max": 100000 }.
sortOrderarray of object3 fields
Specify how results should be sorted
What to order by. 'relevance' is the search score. 'recentActivity' is the episode's publication date when searching episodes, and the podcast's most recent episode date when searching podcasts. 'title' orders alphabetically. 'appleReviews' and 'spotifyReviews' order by a rating that weighs the number of reviews as well as the average, so a 5.0 from three listeners does not outrank a 4.7 from thousands.
Where results that have no value for this field go. Defaults to 'last'. Ignored for 'relevance', which every result has.
Return the opening of each matching episode transcript alongside the result, as transcriptTextSnippet. Episodes with no transcript return null.
How many characters of the transcript includeTranscriptSnippet returns. Defaults to 500. This is the start of the transcript, not the part that matched — for the matching text, search the transcript target and read the highlights.
How many characters each highlighted transcript fragment contains when a search term targets the transcript. Defaults to 300.
Restrict results to these specific episode IDs
Only episodes published on or after this date (inclusive)
Only episodes published strictly before this date (exclusive). Combine with publishedSince for a bounded window, e.g. publishedSince=90 days ago + publishedBefore=30 days ago.
Filter to episodes that have a transcript (true) or that do not (false)
Only episodes whose Pod Engine record changed on or after this date. This tracks our record, not the show's own updates, so use it to pick up everything that has changed since your last sync.
Only episodes added to Pod Engine on or after this date. An episode is added when we first index it, which can be well after it was published — use publishedSince to filter on the publication date instead.
personFiltersarray of object6 fields
Filter episodes by the people on them. Entries are ANDed together, e.g. [{ "name": "Elon Musk", "type": "guest" }, { "name": "Joe Rogan", "type": "host" }] returns only episodes where Elon Musk appeared as a guest and Joe Rogan was a host. An entry with matchMode "not" instead excludes episodes featuring that person.
The name to match
'must' (default) only returns episodes matching this entry; 'not' excludes episodes matching this entry
Whether to match the name as a phrase (all words, in order). Defaults to true; set false for a loose per-word match.
How many words apart tokens can appear in a name to still count as a phrase match
Whether to tolerate close spellings. Uses per-word fuzzy matching with all words required, so it ignores word order and cannot be combined with slop.
sponsorFiltersarray of object5 fields
Filter episodes by sponsor / advertiser name. Entries are ANDed together; an entry with matchMode "not" instead excludes episodes with that sponsor.
The name to match
'must' (default) only returns episodes matching this entry; 'not' excludes episodes matching this entry
Whether to match the name as a phrase (all words, in order). Defaults to true; set false for a loose per-word match.
How many words apart tokens can appear in a name to still count as a phrase match
Whether to tolerate close spellings. Uses per-word fuzzy matching with all words required, so it ignores word order and cannot be combined with slop.
searchResultsStatsobjectrequired3 fields
Search results. Each hit in result.hits combines episode and parent-podcast fields, including podcastId, episodeGuestsAndHosts (array of {name, type: guest|host|unknown|mentioned, roles[], organizations[], image_url}) and episodeSponsorsAndAdvertisers (array of {name, snippet, coupon_codes: string|null, urls[]}). The roles and organizations arrays are currently always empty. An empty array for either episodeGuestsAndHosts or episodeSponsorsAndAdvertisers can mean analysis is missing or completed analysis found no matching people or sponsors; these cases cannot be distinguished from the array alone. Responses with populated sponsor snippets can be large.