Search Episode Transcript

POST https://api.podengine.ai/api/v1/search/episodes/:episodeId/transcript

Search within the transcript of the episode identified by episodeId in the URL. Send the original searchOptions, pageSize and optional cursor in the body; do not repeat episodeId in the body. Count and browse matching passages for that episode. The best passage is separate from paginated additional passages. Counts are exact (eq) or lower bounds (gte); at most 100 passages can be browsed. Initial episode totals still count episodes. Reuse nextCursor with the same episode and query; HTTP 409 means restart without the cursor. Passages use the same Elasticsearch analyzer and sentence boundaries as matchSnippet; nearby terms in one passage count once. Highlighting failures, including transcripts exceeding the index analysis limit, are errors, never zero matches or silently partial counts.

API token required Markdown for LLMs

OpenAPI spec

Example request

Install & configure

curl -X POST "https://api.podengine.ai/api/v1/search/episodes/:episodeId/transcript" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_TOKEN" \
  -d '{
  "searchOptions": {
    "searchTerms": [
      {
        "searchTerm": "artificial intelligence",
        "searchType": "text",
        "searchTargets": [
          "transcript"
        ],
        "searchTermOptions": {
          "matchMode": "must",
          "phraseMatch": true
        }
      }
    ]
  },
  "pageSize": 5
}'

const options = {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
  },
  body: JSON.stringify({
  "searchOptions": {
    "searchTerms": [
      {
        "searchTerm": "artificial intelligence",
        "searchType": "text",
        "searchTargets": [
          "transcript"
        ],
        "searchTermOptions": {
          "matchMode": "must",
          "phraseMatch": true
        }
      }
    ]
  },
  "pageSize": 5
})
};

fetch("https://api.podengine.ai/api/v1/search/episodes/:episodeId/transcript", options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

import requests

headers = {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"
}

response = requests.post("https://api.podengine.ai/api/v1/search/episodes/:episodeId/transcript", headers=headers, json={
  "searchOptions": {
    "searchTerms": [
      {
        "searchTerm": "artificial intelligence",
        "searchType": "text",
        "searchTargets": [
          "transcript"
        ],
        "searchTermOptions": {
          "matchMode": "must",
          "phraseMatch": true
        }
      }
    ]
  },
  "pageSize": 5
})
print(response.json())

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "YOUR_API_TOKEN");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var json = @"{
  ""searchOptions"": {
    ""searchTerms"": [
      {
        ""searchTerm"": ""artificial intelligence"",
        ""searchType"": ""text"",
        ""searchTargets"": [
          ""transcript""
        ],
        ""searchTermOptions"": {
          ""matchMode"": ""must"",
          ""phraseMatch"": true
        }
      }
    ]
  },
  ""pageSize"": 5
}";
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.podengine.ai/api/v1/search/episodes/:episodeId/transcript", content);
var data = await response.Content.ReadAsStringAsync();
Console.WriteLine(data);

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	jsonData := []byte(`{
  "searchOptions": {
    "searchTerms": [
      {
        "searchTerm": "artificial intelligence",
        "searchType": "text",
        "searchTargets": [
          "transcript"
        ],
        "searchTermOptions": {
          "matchMode": "must",
          "phraseMatch": true
        }
      }
    ]
  },
  "pageSize": 5
}`)
	body := bytes.NewBuffer(jsonData)
	req, _ := http.NewRequest("POST", "https://api.podengine.ai/api/v1/search/episodes/:episodeId/transcript", body)
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "YOUR_API_TOKEN")
	
	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

import { PodEngine } from '@podengine/sdk';

const pe = new PodEngine({ apiKey: process.env.PODENGINE_API_KEY });

const data = await pe.search.getTranscriptPassages({
  episodeId: '316bcb29-3017-46d1-88ee-af5a6505a484',
  searchOptions: {
    searchTerms: [
      {
        searchTerm: 'artificial intelligence',
        searchType: 'text',
        searchTargets: ['transcript'],
        searchTermOptions: {
          matchMode: 'must',
          phraseMatch: true,
        },
      },
    ],
  },
  pageSize: 5,
});

console.log(data);

import os

from podengine import PodEngine

pe = PodEngine(api_key=os.environ["PODENGINE_API_KEY"])

data = pe.search.get_transcript_passages(
    episode_id="316bcb29-3017-46d1-88ee-af5a6505a484",
    search_options={
        "searchTerms": [
            {
                "searchTerm": "artificial intelligence",
                "searchType": "text",
                "searchTargets": ["transcript"],
                "searchTermOptions": {
                    "matchMode": "must",
                    "phraseMatch": True,
                },
            },
        ],
    },
    page_size=5,
)

print(data)

200

Example response

{
  "status": "OK",
  "data": {
    "episodeId": "0eaa5978-d577-48fd-bc2a-68fb355b41e1",
    "bestPassage": {
      "id": "string",
      "text": "string"
    },
    "passages": [
      {
        "id": "string",
        "text": "string"
      }
    ],
    "total": {
      "value": 0,
      "relation": "eq"
    },
    "additionalCount": 0,
    "hasMore": true,
    "nextCursor": "string",
    "truncated": true,
    "passageLimit": 100
  }
}

Request

Path parameters

episodeIdstringrequireduuid

Pod Engine UUID of the episode.

Request body

searchOptionsobjectrequired41 fields

Original episode search options, including all positive and excluded terms. Episode pagination is ignored.

cursorstringnullable

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

pageSizeinteger1 – 1000

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.

projectIdstringrequired

The Pod Engine Project ID

excludeIgnoredPodcastsboolean

If true, will not include any podcasts marked as ignored on this project in the results.

excludePodcastsOnListboolean

If true, will not include any podcasts on the project list in the results.

includePodcastRelevancyboolean

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

excludeRelvancyValuesarray of number

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.

forceRecalculateRelevancyboolean

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.

projectIdstring

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

searchTermstringrequiredmin 2 characters

The text to look for. Wrapping it in single or double quotes forces a phrase match, the same as setting searchTermOptions.phraseMatch.

searchTypeenumrequired

How to match the term. 'text' runs keyword matching against each of the searchTargets.

text

searchTargetsarray of enumrequired

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.

podcast-titlepodcast-descriptionepisode-titleepisode-descriptiontranscript

searchTermOptionsobject4 fields

How this term is matched: whether it is required, treated as a phrase, or matched loosely.

matchModeenumdefault "optional"

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.

mustnotoptional

phraseMatchboolean

Whether to match the search term as a phrase

slopnumber

How many words apart tokens can appear in a document to be considered a match

fuzzyboolean

Whether to use fuzzy matching

excludeItunesGenresarray of string

iTunes genres to exclude from results

excludePodcastIdsarray of string

Specific podcast IDs to exclude from results

excludeEpisodeIdsarray of string

Specific episode IDs to exclude from results

explicitenum

Filter by explicit content rating

cleanexplicit

foundedSinceany

Filter podcasts founded after this date

hasPrimaryContactboolean

Filter podcasts that have primary contact information

hasSocialsarray of enum

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

beehiivbehanceblueskydiscordfacebookgithubinstagramlinkedinlinktreemastodonmediumpatreonpinterestredditsnapchatsoundcloudsubstackthreadstiktoktumblrtwitchtwittervimeowhatsappyoutube

includeItunesGenresarray of string

iTunes genres to include in results

includePodcastIdsarray of string

Specific podcast IDs to include in results

languagesarray of string

Filter podcasts by language

lastEpisodeDateSincedate

Filter podcasts with episodes published after this date

maxTotalEpisodesintegermin 1

Maximum number of total episodes

minCastboxPlaysintegermin 1

Minimum number of Castbox plays

minCastboxSubscribersintegermin 1

Minimum number of Castbox subscribers

minItunesRatingnumber0 – 5

Minimum iTunes rating score

minItunesRatingCountintegermin 1

Minimum number of iTunes ratings

minSpotifyRatingnumber0 – 5

Minimum Spotify rating score

minSpotifyRatingCountintegermin 1

Minimum number of Spotify ratings

minTotalEpisodesintegermin 1

Minimum number of total episodes

podcastCountriesarray of string

Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us

podcastHasGuestsboolean

Filter podcasts that feature guests

podcastAuthorityScoreobject5 fields

Filter podcasts by their Authority Score

authorityScoreobject2 fields

Restrict results to podcasts whose overall Authority Score falls in this range. The overall score combines the quality, engagement, social and YouTube components; podcasts we have not scored are excluded. See https://www.podengine.ai/podcast-authority-score.