Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Listen Notes

Scalekit connector
Open markdown

The Listen Notes connector lets your AI agent act in each user's Listen Notes account. Each user connects their own Listen Notes API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 23 tools.

Tools
23
What they doRead · write · destructive
23 · 0 · 023 read0 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Listen Notes connection

    In AgentKit > Connections, create a Listen Notes connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'listennotes'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Listen Notes:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'listennotes_get_podcasts_batch',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Listen Notes credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • listennotes_get_curated_listGet one curated podcast list with full metadata for every podcast in it.Read-only

    Get Curated Podcast List

    Get one curated podcast list with full metadata for every podcast in it. Same data as listennotes.com/curated-podcasts. Returns id, title, description, source_url, source_domain, pub_date_ms, total and podcasts (id, title, publisher, description, listen_score and other metadata). Use listennotes_get_curated_list once you have a list ID. Use listennotes_list_curated_lists or listennotes_search with type curated to find list IDs.

    Inputs

    idstringrequired
    Curated list ID, from listennotes_list_curated_lists or a listennotes_search result with type curated. Example: SDFKduyJ47r.
  • listennotes_get_episodeGet one episode's full metadata, optionally with its transcript.Read-only

    Get Episode

    Get one episode's full metadata, optionally with its transcript. Returns title, description, audio URL, audio_length_sec, pub_date_ms, explicit_content, link, listennotes_url, the parent podcast's metadata and, when show_transcript is 1 and one exists, transcript. Fewer than 1% of episodes have transcripts, and transcripts need a PRO or ENTERPRISE plan. Use listennotes_get_episode for one episode's details. Use listennotes_get_episodes_batch for basic metadata on up to 10 episodes at once.

    Inputs

    idstringrequired
    Listen Notes episode ID (32-character hex string), from the id field of a search or podcast episode result. Example: 6b6d65930c5a4f71b254465871fed370.
    show_transcriptinteger
    Set to 1 to include the transcript, when one exists. Off (0) by default because it makes the response large. Needs a PRO or ENTERPRISE plan.one of 01
  • listennotes_get_episode_recommendationsGet up to 8 episodes similar to a given episode.Read-only

    Get Episode Recommendations

    Get up to 8 episodes similar to a given episode. Returns recommendations: episodes with id, title, description, audio URL, length, pub_date_ms and parent podcast. Use listennotes_get_episode_recommendations for 'more like this' episodes. Use listennotes_get_podcast_recommendations for similar podcasts.

    Inputs

    idstringrequired
    Listen Notes episode ID (32-character hex string), from the id field of a search or podcast episode result. Example: 6b6d65930c5a4f71b254465871fed370.
    safe_modeinteger
    Set to 1 to exclude episodes with explicit language; 0 (the default) keeps them.one of 01
  • listennotes_get_episodes_batchGet basic metadata for up to 10 episodes in one call.Read-only

    Get Episodes in Batch

    Get basic metadata for up to 10 episodes in one call. Needs a PRO or ENTERPRISE plan. Returns episodes: id, title, description, audio URL, audio_length_sec, pub_date_ms and parent podcast for each ID found. IDs not found are left out. Use listennotes_get_episodes_batch to load several known episodes at once, for example a saved list. Use listennotes_get_episode for one episode's full details or transcript.

    Inputs

    idsstringrequired
    Comma-separated Listen Notes episode IDs, up to 10. Example: c577d55b2b2b483c969fae3ceb58e362,0f34a9099579490993eec9e8c8cebb82.
  • listennotes_get_playlistGet a playlist's details and its items, 20 at a time.Read-only

    Get Playlist

    Get a playlist's details and its items, 20 at a time. Works for playlists the API account can access and for any public or unlisted playlist. Returns id, name, description, visibility, type, total, total_audio_length_sec, last_timestamp_ms (the paging cursor) and items: id, type (episode, podcast or custom audio), notes, added_at_ms and the item's data. Use listennotes_get_playlist to read a playlist's contents. Use listennotes_list_playlists to find playlist IDs.

    Inputs

    idstringrequired
    Playlist ID: 11 characters, also the last part of a playlist URL (listennotes.com/listen/podcasts-about-podcasting-m1pe7z60bsw has ID m1pe7z60bsw). Example: m1pe7z60bsw.
    last_timestamp_msinteger
    For paging through items: pass last_timestamp_ms from the previous response (a Unix timestamp in milliseconds). Omit or use 0 for the first 20 items. Example: 1600000000000.
    sortstring
    Item order: recent_added_first (the default), oldest_added_first, recent_published_first or oldest_published_first.one of recent_added_firstoldest_added_firstrecent_published_firstoldest_published_first
    typestring
    Which view to return: episode_list or podcast_list. Omit to use the playlist's saved default view.one of episode_listpodcast_list
  • listennotes_get_podcastGet one podcast's full metadata and up to 10 of its episodes per call.Read-only

    Get Podcast

    Get one podcast's full metadata and up to 10 of its episodes per call. Returns title, publisher, description, website, rss, language, country, genre_ids, total_episodes, listen_score, social links (extra), looking_for, and episodes (id, title, description, audio URL, length, pub_date_ms), plus next_episode_pub_date for paging. An empty episodes array means there are no more episodes. Use listennotes_get_podcast for one podcast and its episode list. Use listennotes_get_podcasts_batch for basic metadata on up to 10 podcasts at once.

    Inputs

    idstringrequired
    Listen Notes podcast ID (32-character hex string), from the id field of a search, best-podcasts or other podcast result. Example: 4d3fe717742d4963a85562e9f84d8c79.
    next_episode_pub_dateinteger
    For paging through episodes: pass next_episode_pub_date from the previous response (a Unix timestamp in milliseconds). Omit to get the newest or oldest 10, depending on sort. Example: 1479154463000.
    sortstring
    Episode order: recent_first (the default) or oldest_first.one of recent_firstoldest_first
  • listennotes_get_podcast_audienceGet a podcast's audience breakdown by country, as measured on Listen Notes.Read-only

    Get Podcast Audience

    Get a podcast's audience breakdown by country, as measured on Listen Notes. Not every podcast has data. Returns by_regions: a list of region names with the share (ratio) of the audience from each. Use listennotes_get_podcast_audience to see where a podcast's listeners are. Use listennotes_get_podcast for the podcast's metadata and listen_score.

    Inputs

    idstringrequired
    Listen Notes podcast ID (32-character hex string), from the id field of a search, best-podcasts or other podcast result. Example: 4d3fe717742d4963a85562e9f84d8c79.
  • listennotes_get_podcast_recommendationsGet up to 8 podcasts similar to a given podcast.Read-only

    Get Podcast Recommendations

    Get up to 8 podcasts similar to a given podcast. Returns recommendations: podcasts with id, title, publisher, description, total_episodes, listen_score and other metadata. Use listennotes_get_podcast_recommendations for 'more like this' podcasts. Use listennotes_get_episode_recommendations for similar episodes.

    Inputs

    idstringrequired
    Listen Notes podcast ID (32-character hex string), from the id field of a search, best-podcasts or other podcast result. Example: 4d3fe717742d4963a85562e9f84d8c79.
    safe_modeinteger
    Set to 1 to exclude podcasts with explicit language; 0 (the default) keeps them.one of 01
All 51 in Search