API recipe

Find Your Next Podcast Guest

Build a guest shortlist from recent appearances on podcasts your audience already enjoys.

beginner 10 minutes PodEngine Team

PodcastsGuestsHosting

Before you start

API token
The Pod Engine ID or slug of a similar podcast

Choose your example

Your selection applies to every step. HTTP uses built-in clients without the Pod Engine libraries.

Use Node.js 22 or newer. Save the complete script as recipe.mjs.

npm install @podengine/sdk
# macOS / Linux shell; set the same variable in your shell on Windows
export PODENGINE_API_KEY="YOUR_API_KEY"
node recipe.mjs

Use Node.js 22 or newer. Save the complete script as recipe.mjs. No package installation is needed.

# macOS / Linux shell; set the same variable in your shell on Windows
export PODENGINE_API_KEY="YOUR_API_KEY"
node recipe.mjs

Use Python 3.10 or newer. Save the complete script as recipe.py.

python -m pip install podengine
# macOS / Linux shell; set the same variable in your shell on Windows
export PODENGINE_API_KEY="YOUR_API_KEY"
python recipe.py

Use Python 3.10 or newer. Save the complete script as recipe.py. No package installation is needed.

# macOS / Linux shell; set the same variable in your shell on Windows
export PODENGINE_API_KEY="YOUR_API_KEY"
python recipe.py

Set up the client

Start your file with this setup, then append each step in order. The complete script below includes everything.

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

const apiKey = process.env.PODENGINE_API_KEY;
if (!apiKey) throw new Error('Set PODENGINE_API_KEY before running this recipe');
const pe = new PodEngine({
  apiKey,
  baseUrl: process.env.PODENGINE_API_URL || 'https://api.podengine.ai',
});

const apiKey = process.env.PODENGINE_API_KEY;
if (!apiKey) throw new Error('Set PODENGINE_API_KEY before running this recipe');
const baseUrl = process.env.PODENGINE_API_URL || 'https://api.podengine.ai';

async function request(path, body) {
  const response = await fetch(`${baseUrl}${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  if (!response.ok) throw new Error(`Pod Engine request failed: ${response.status} ${response.statusText}`);
  return (await response.json()).data;
}

import os
from podengine import PodEngine

pe = PodEngine(
    api_key=os.environ["PODENGINE_API_KEY"],
    base_url=os.environ.get("PODENGINE_API_URL", "https://api.podengine.ai"),
)

import json
import os
from urllib.parse import urlencode, quote
from urllib.request import Request, urlopen

api_key = os.environ["PODENGINE_API_KEY"]
base_url = os.environ.get("PODENGINE_API_URL", "https://api.podengine.ai")


def request(path, body=None):
    req = Request(
        base_url + path,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": api_key, "Content-Type": "application/json"},
        method="POST" if body is not None else "GET",
    )
    # urlopen raises HTTPError for non-success responses.
    with urlopen(req, timeout=30) as response:
        return json.load(response)["data"]

Complete runnable script

Download script

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

const apiKey = process.env.PODENGINE_API_KEY;
if (!apiKey) throw new Error('Set PODENGINE_API_KEY before running this recipe');
const pe = new PodEngine({
  apiKey,
  baseUrl: process.env.PODENGINE_API_URL || 'https://api.podengine.ai',
});

const podcastIdOrSlug = 'this-week-in-startups';
const { podcast, guests: summary } = await pe.podcasts.getPodcastGuests({
  podcastIdOrSlug,
  sinceDays: 90,
  role: 'guest',
});
console.table([
  {
    podcast: podcast.title,
    analyzedEpisodes: summary.episodesCount,
    oldestAnalyzedEpisode: summary.oldestEpisodeDate,
    newestAnalyzedEpisode: summary.mostRecentEpisodeDate,
  },
]);

const shortlist = [...summary.guests]
  .sort((a, b) => new Date(b.mostRecentAppearanceDate).getTime() - new Date(a.mostRecentAppearanceDate).getTime())
  .slice(0, 10)
  .map((item) => ({
    name: item.name,
    appearances: item.appearancesCount,
    latestAppearance: item.mostRecentAppearanceDate,
    sourcePodcast: podcast.title,
  }));
if (summary.episodesCount === 0) {
  console.info('No analyzed episodes. Try a wider window or another show.');
} else if (!shortlist.length) {
  console.info('No guests returned from the analyzed episodes.');
} else {
  console.table(shortlist);
}

Download script

const apiKey = process.env.PODENGINE_API_KEY;
if (!apiKey) throw new Error('Set PODENGINE_API_KEY before running this recipe');
const baseUrl = process.env.PODENGINE_API_URL || 'https://api.podengine.ai';

async function request(path, body) {
  const response = await fetch(`${baseUrl}${path}`, {
    method: body === undefined ? 'GET' : 'POST',
    headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });
  if (!response.ok) throw new Error(`Pod Engine request failed: ${response.status} ${response.statusText}`);
  return (await response.json()).data;
}

const podcastIdOrSlug = 'this-week-in-startups';
const { podcast, guests: summary } = await request(
  `/api/v1/podcasts/${encodeURIComponent(podcastIdOrSlug)}/guests?${new URLSearchParams({ sinceDays: '90', role: 'guest' })}`
);
console.table([
  {
    podcast: podcast.title,
    analyzedEpisodes: summary.episodesCount,
    oldestAnalyzedEpisode: summary.oldestEpisodeDate,
    newestAnalyzedEpisode: summary.mostRecentEpisodeDate,
  },
]);

const shortlist = [...summary.guests]
  .sort((a, b) => new Date(b.mostRecentAppearanceDate).getTime() - new Date(a.mostRecentAppearanceDate).getTime())
  .slice(0, 10)
  .map((item) => ({
    name: item.name,
    appearances: item.appearancesCount,
    latestAppearance: item.mostRecentAppearanceDate,
    sourcePodcast: podcast.title,
  }));
if (summary.episodesCount === 0) {
  console.info('No analyzed episodes. Try a wider window or another show.');
} else if (!shortlist.length) {
  console.info('No guests returned from the analyzed episodes.');
} else {
  console.table(shortlist);
}

Download script

import os
from podengine import PodEngine

pe = PodEngine(
    api_key=os.environ["PODENGINE_API_KEY"],
    base_url=os.environ.get("PODENGINE_API_URL", "https://api.podengine.ai"),
)

podcast_id_or_slug = "this-week-in-startups"
data = pe.podcasts.get_podcast_guests(
    podcast_id_or_slug=podcast_id_or_slug, since_days=90, role="guest"
).model_dump(by_alias=True, mode="json")
podcast, summary = data["podcast"], data["guests"]
print(
    {
        "podcast": podcast["title"],
        "analyzedEpisodes": summary["episodesCount"],
        "oldestAnalyzedEpisode": summary["oldestEpisodeDate"],
        "newestAnalyzedEpisode": summary["mostRecentEpisodeDate"],
    }
)

shortlist = sorted(
    summary["guests"], key=lambda item: item["mostRecentAppearanceDate"], reverse=True
)[:10]
if summary["episodesCount"] == 0:
    print("No analyzed episodes. Try a wider window or another show.")
elif not shortlist:
    print("No guests returned from the analyzed episodes.")
else:
    for item in shortlist:
        print(
            {
                "name": item["name"],
                "appearances": item["appearancesCount"],
                "latestAppearance": item["mostRecentAppearanceDate"],
                "sourcePodcast": podcast["title"],
            }
        )

Download script

import json
import os
from urllib.parse import urlencode, quote
from urllib.request import Request, urlopen

api_key = os.environ["PODENGINE_API_KEY"]
base_url = os.environ.get("PODENGINE_API_URL", "https://api.podengine.ai")


def request(path, body=None):
    req = Request(
        base_url + path,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": api_key, "Content-Type": "application/json"},
        method="POST" if body is not None else "GET",
    )
    # urlopen raises HTTPError for non-success responses.
    with urlopen(req, timeout=30) as response:
        return json.load(response)["data"]

podcast_id_or_slug = "this-week-in-startups"
data = request(
    f"/api/v1/podcasts/{quote(podcast_id_or_slug, safe='')}/guests?"
    + urlencode({"sinceDays": 90, "role": "guest"})
)
podcast, summary = data["podcast"], data["guests"]
print(
    {
        "podcast": podcast["title"],
        "analyzedEpisodes": summary["episodesCount"],
        "oldestAnalyzedEpisode": summary["oldestEpisodeDate"],
        "newestAnalyzedEpisode": summary["mostRecentEpisodeDate"],
    }
)

shortlist = sorted(
    summary["guests"], key=lambda item: item["mostRecentAppearanceDate"], reverse=True
)[:10]
if summary["episodesCount"] == 0:
    print("No analyzed episodes. Try a wider window or another show.")
elif not shortlist:
    print("No guests returned from the analyzed episodes.")
else:
    for item in shortlist:
        print(
            {
                "name": item["name"],
                "appearances": item["appearancesCount"],
                "latestAppearance": item["mostRecentAppearanceDate"],
                "sourcePodcast": podcast["title"],
            }
        )

Find recent guests on a similar show

Choose a podcast with a similar audience and interview format. Its recent guests can give you ideas for people and topics to bring to your own show.

Choose your language and SDK or HTTP above. Run the setup first, then append each step to the same file. Replace the example podcast slug with your chosen show.

The Podcast Guests endpoint accepts sinceDays=90 to look back 90 days and role=guest to exclude hosts. In the HTTP response, the summary is at data.guests and the people at data.guests.guests.

const podcastIdOrSlug = 'this-week-in-startups';
const { podcast, guests: summary } = await pe.podcasts.getPodcastGuests({
  podcastIdOrSlug,
  sinceDays: 90,
  role: 'guest',
});
console.table([
  {
    podcast: podcast.title,
    analyzedEpisodes: summary.episodesCount,
    oldestAnalyzedEpisode: summary.oldestEpisodeDate,
    newestAnalyzedEpisode: summary.mostRecentEpisodeDate,
  },
]);

const podcastIdOrSlug = 'this-week-in-startups';
const { podcast, guests: summary } = await request(
  `/api/v1/podcasts/${encodeURIComponent(podcastIdOrSlug)}/guests?${new URLSearchParams({ sinceDays: '90', role: 'guest' })}`
);
console.table([
  {
    podcast: podcast.title,
    analyzedEpisodes: summary.episodesCount,
    oldestAnalyzedEpisode: summary.oldestEpisodeDate,
    newestAnalyzedEpisode: summary.mostRecentEpisodeDate,
  },
]);

podcast_id_or_slug = "this-week-in-startups"
data = pe.podcasts.get_podcast_guests(
    podcast_id_or_slug=podcast_id_or_slug, since_days=90, role="guest"
).model_dump(by_alias=True, mode="json")
podcast, summary = data["podcast"], data["guests"]
print(
    {
        "podcast": podcast["title"],
        "analyzedEpisodes": summary["episodesCount"],
        "oldestAnalyzedEpisode": summary["oldestEpisodeDate"],
        "newestAnalyzedEpisode": summary["mostRecentEpisodeDate"],
    }
)

podcast_id_or_slug = "this-week-in-startups"
data = request(
    f"/api/v1/podcasts/{quote(podcast_id_or_slug, safe='')}/guests?"
    + urlencode({"sinceDays": 90, "role": "guest"})
)
podcast, summary = data["podcast"], data["guests"]
print(
    {
        "podcast": podcast["title"],
        "analyzedEpisodes": summary["episodesCount"],
        "oldestAnalyzedEpisode": summary["oldestEpisodeDate"],
        "newestAnalyzedEpisode": summary["mostRecentEpisodeDate"],
    }
)

Notes

sinceDays accepts whole numbers from 1 to 365. Without it, the endpoint uses the last 10 episodes and may run missing AI analysis on demand.
Windowed requests only use existing analysis; they do not trigger new AI analysis. episodesCount is the number of analyzed episodes included, not all episodes published in the window.
Only the 500 newest episodes in the window are considered. Missing analysis is skipped, so this is not a complete guest history.

Build a shortlist of recent appearances

Append this code to the same file. It sorts guests by their latest appearance and keeps ten names to research. The appearance dates refer to episode publication dates.

Check the analyzed episode count and date range alongside the names. An empty result does not prove the show had no guests; there may be no usable analysis in your chosen window. When no analyzed episodes are included, the summary dates are null.

const shortlist = [...summary.guests]
  .sort((a, b) => new Date(b.mostRecentAppearanceDate).getTime() - new Date(a.mostRecentAppearanceDate).getTime())
  .slice(0, 10)
  .map((item) => ({
    name: item.name,
    appearances: item.appearancesCount,
    latestAppearance: item.mostRecentAppearanceDate,
    sourcePodcast: podcast.title,
  }));
if (summary.episodesCount === 0) {
  console.info('No analyzed episodes. Try a wider window or another show.');
} else if (!shortlist.length) {
  console.info('No guests returned from the analyzed episodes.');
} else {
  console.table(shortlist);
}

const shortlist = [...summary.guests]
  .sort((a, b) => new Date(b.mostRecentAppearanceDate).getTime() - new Date(a.mostRecentAppearanceDate).getTime())
  .slice(0, 10)
  .map((item) => ({
    name: item.name,
    appearances: item.appearancesCount,
    latestAppearance: item.mostRecentAppearanceDate,
    sourcePodcast: podcast.title,
  }));
if (summary.episodesCount === 0) {
  console.info('No analyzed episodes. Try a wider window or another show.');
} else if (!shortlist.length) {
  console.info('No guests returned from the analyzed episodes.');
} else {
  console.table(shortlist);
}

shortlist = sorted(
    summary["guests"], key=lambda item: item["mostRecentAppearanceDate"], reverse=True
)[:10]
if summary["episodesCount"] == 0:
    print("No analyzed episodes. Try a wider window or another show.")
elif not shortlist:
    print("No guests returned from the analyzed episodes.")
else:
    for item in shortlist:
        print(
            {
                "name": item["name"],
                "appearances": item["appearancesCount"],
                "latestAppearance": item["mostRecentAppearanceDate"],
                "sourcePodcast": podcast["title"],
            }
        )

shortlist = sorted(
    summary["guests"], key=lambda item: item["mostRecentAppearanceDate"], reverse=True
)[:10]
if summary["episodesCount"] == 0:
    print("No analyzed episodes. Try a wider window or another show.")
elif not shortlist:
    print("No guests returned from the analyzed episodes.")
else:
    for item in shortlist:
        print(
            {
                "name": item["name"],
                "appearances": item["appearancesCount"],
                "latestAppearance": item["mostRecentAppearanceDate"],
                "sourcePodcast": podcast["title"],
            }
        )

Turn the shortlist into interview ideas

For each candidate, listen to a recent interview and write down one question your audience would want answered that the other show did not cover. Prioritize guests whose experience fits your next few episodes, then use their public website or booking channel to prepare a personal invitation.

Repeat with a few similar shows to broaden the list. Check identities before combining matching names across podcasts.

For host collaborations or crossover episodes, change the request to role=host. Omit role to include guests, hosts, and mentioned people. The role filter changes the people returned; episodesWithGuestsCount still counts analyzed episodes containing guests.

The summary provides names, appearance counts, and dates. It does not provide guest contact details or booking availability.