API & MCP

Get a transcription

Poll the job, or let a webhook tell you when it is finished, then read the text and segments.

In short

GET /api/v1/transcriptions/{id} returns the job's status plus, once it is done, the full text, the summary, and speaker-labeled segments with start and end times. Poll until status is done or failed, or register a webhook and skip the polling entirely.

Poll the job

Poll GET /api/v1/transcriptions/{id} until status reads done or failed. The response carries the language, duration, word count, billed minutes, the full text, the summary, and a segments array of timed, speaker-labeled lines.

Response

{
  "id": "…",
  "status": "done",
  "language": "en",
  "duration_seconds": 1771,
  "word_count": 4120,
  "billed_minutes": 30,
  "text": "Full transcript…",
  "summary": "…",
  "segments": [
    { "start": 0.0, "end": 4.2, "speaker": "Speaker 1", "text": "Welcome back." }
  ]
}

List recent jobs

GET /api/v1/transcriptions lists your transcriptions, which is the cheap way to find a job id you no longer have to hand – for example when reconciling what an automated run produced.

Skip the polling

If you are wiring this into a service, a webhook is the better shape than a polling loop: Pepys posts transcription.completed or transcription.failed to your endpoint and you fetch the full transcript only once, when there is actually something to fetch.

Get a transcription – questions, answered

How do I know when a transcription has finished?

Poll GET /api/v1/transcriptions/{id} until status is done or failed, or register a webhook and receive a signed POST on transcription.completed or transcription.failed instead.

What does the response include?

Status, language, duration in seconds, word count, billed minutes, the full text, the summary, and a segments array with start, end, speaker, and text for each line.

How do I list my transcriptions?

GET /api/v1/transcriptions returns your jobs, which is useful for recovering a job id you no longer have.

Do the segments include speaker labels?

Yes, when the job ran with diarization each segment carries a speaker field alongside its start and end times.

Try it on your own audio

Create a free account and transcribe a recording – 60 minutes are included, no card required. Still stuck? Email contact@pepys.co or see the support page.