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.
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.
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
resultobjectrequired4 fields
Highest relevance score in the result set, or null when unavailable.
Number of hits returned in this page.
hitsarray of objectrequired145 fields
Matching episodes with parent podcast fields. Optional fields depend on the requested field selections.
Whether the hit has a transcript ID.
episodeSponsorsAndAdvertisersarray of objectnullable4 fields
Detected sponsors and advertisers with transcript snippets. An empty array can mean analysis is missing or found no sponsors.
The name of the sponsor.
An array of URLs associated with the sponsor.
A brief snippet or description of the sponsor.
Any coupon codes provided by the sponsor, if applicable.
episodeGuestsAndHostsarray of objectnullable5 fields
Detected episode guests, hosts, and mentions. Roles and organizations are currently empty. An empty array can mean analysis is missing or found no matching people.
The name of the guest.
How the person appears in the episode: guest, host, unknown, or mentioned.
An array of possible job roles and titles
An array of organizations the guest is affiliated with.
The URL of the guest image, if available.
chartPositionsarray of objectnullable10 fields
The date of the chart position in YYYY-MM-DD format.
The type of chart (e.g., "apple", "spotify").
The ISO country code where this chart position applies.
The main category of the chart (e.g., "top podcasts").
The sub-category of the chart, if applicable.
The current position of the podcast on the chart.
The previous position of the podcast on the chart.
The change in position from the previous chart (positive = moved up, negative = moved down).
The total number of days the podcast has been on this chart.
The number of consecutive days the podcast has been on this chart.
podcastSocialMediaLinksarray of object2 fields
similarPodcastsarray of object4 fields
youtubeChannelsarray of object10 fields
Search relevance score; zero when Elasticsearch does not return a score.
Opening transcript excerpt, when requested and available.