Download Transcript

GET

/api/public/episode/transcript

Returns an episode’s transcript and transcription status, with episode and show details.

Getting a transcript

Call with start_if_missing=true. If the episode has not been transcribed yet, this starts a transcription job and transcription.status comes back as Running.
Call again until transcription.status is Done or Failed.
When it is Done, read transcription.text.

Status	Meaning
`NotStarted`	The episode has not been transcribed. Send `start_if_missing=true` to start.
`Running`	Transcription is in progress.
`Done`	The transcript is ready in `transcription.text`.
`Failed`	Transcription failed. `start_if_missing` does not restart it; contact support.

If no episode matches itunes_or_yt_id and guid, the response is 200 with an empty object {}.

Reading transcription.text

transcription.text is always a string. With format=text it is the transcript as plain text. With format=timestamps (the default) it is a JSON array of word objects encoded as a string, so parse it a second time:

const words = JSON.parse(response.transcription.text);

Until the status is Done, text is "[]" with format=timestamps and "" with format=text.

Each word object has these fields:

Field	Type	Example	Description
`word`	string	`Hello`	The transcribed word.
`startTime`	number	`0.075`	When the word starts, in seconds from the beginning of the audio.
`endTime`	number	`0.365`	When the word ends, in seconds from the beginning of the audio.
`confidence`	number	`0.99`	Transcription confidence, from 0 to 1.
`speaker`	integer or string	`0`	Speaker label within this episode. Some transcripts give it as a numeric string, such as `"0"`. Words inside a detected ad have `"ADVERTISER"`.
`isAd`	boolean	`true`	`true` on words inside a detected ad. Absent on other words.

Daily limit

Each transcription job that start_if_missing starts counts toward a limit of 1,000 jobs per organization per UTC day. Calls that start no job, because the episode is already Running, Done or Failed or no episode matches, do not count. Over the limit, the call returns 429.

Download Transcript

const url = 'https://backend.podscribe.ai/api/public/episode/transcript?itunes_or_yt_id=1200361736&guid=example&format=timestamps&start_if_missing=false';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://backend.podscribe.ai/api/public/episode/transcript"

querystring = {"itunes_or_yt_id":"1200361736","guid":"example","format":"timestamps","start_if_missing":"false"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

curl --request GET \
  --url 'https://backend.podscribe.ai/api/public/episode/transcript?itunes_or_yt_id=1200361736&guid=example&format=timestamps&start_if_missing=false' \
  --header 'Authorization: Bearer <token>'

Query Parameters

itunes_or_yt_id

required

string

The show the episode belongs to: its Apple Podcasts (iTunes) ID, such as 1200361736, or its YouTube channel ID (UC…) or playlist ID (PL…).

Example

1200361736

guid

required

string

The episode’s GUID, the <guid> of the episode’s item in the show’s RSS feed.

format

timestamps

timestamps text

How transcription.text is returned. timestamps: a JSON string of word objects with timings and speaker labels. text: the words joined into one plain-text string.

start_if_missing

boolean

false

Start transcribing the episode if its status is NotStarted; the response then has status Running. Has no effect when the status is already Running, Done or Failed, so it is safe to send on every call. Each job it starts counts toward the daily limit.

Response Body

The episode with its transcription. An empty object {} when no episode matches.

application/json

The episode’s ID in Podscribe.

integer

title

Episode title.

string

guid

The episode’s GUID from the show’s feed.

string

description

Episode description.

string

duration

Episode length. Some episodes return it as a string.

number | string nullable

url

URL of the episode’s media file.

string nullable

seriesId

The show’s ID in Podscribe.

integer

artist

The show’s artist (author).

string nullable

seriesLogoUrl

URL of the show’s logo.

string nullable

seriesRssUrl

The show’s RSS feed URL.

string nullable

seriesTitle

Show title.

string

seriesItunesId

The show’s Apple Podcasts (iTunes) ID.

string nullable

categories

The show’s categories, comma-separated.

string nullable

transcription

The episode’s transcription status and transcript.

{status,text}

status

NotStarted: not transcribed yet. Running: in progress. Done: the transcript is in text. Failed: transcription failed.

NotStarted Running Done Failed

text

The transcript. With format=timestamps, a JSON array of word objects encoded as a string; parse it with JSON.parse. With format=text, plain text. Until status is Done: "[]" with format=timestamps, "" with format=text.

string

Response example

{
  "id": 123456789,
  "title": "Episode 42: Hello world",
  "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "description": "In this episode we say hello.",
  "duration": 1830,
  "url": "https://example.com/episodes/42.mp3",
  "seriesId": 98765,
  "artist": "Example Media",
  "seriesLogoUrl": "https://example.com/logo.jpg",
  "seriesRssUrl": "https://example.com/feed.xml",
  "seriesTitle": "Example Show",
  "seriesItunesId": "1200361736",
  "categories": "News,Daily News",
  "transcription": {
    "status": "Done",
    "text": "[{\"word\":\"Hello\",\"startTime\":0.075,\"endTime\":0.365,\"confidence\":0.99,\"speaker\":0},{\"word\":\"world\",\"startTime\":0.385,\"endTime\":0.505,\"confidence\":0.97,\"speaker\":0},{\"word\":\"Try\",\"startTime\":61.2,\"endTime\":61.41,\"confidence\":0.98,\"speaker\":\"ADVERTISER\",\"isAd\":true}]"
  }
}