Blog

A New API Endpoint to Paginate Through Historical Transcripts

Changelog
Share on social icon.Share on social icon.Share on social icon.Share on social icon.

Every day, millions of transcriptions are created using the AssemblyAI API. Developers transcribe videos, podcasts, phone calls, interviews, and a slew of other types of content that we never imagined back when we started the company in 2017.

A common ask we get from developers is for an easy way to query for, and paginate through, all the transcriptions they’ve historically created with the AssemblyAI API. Traditionally, we’ve advised developers to store the IDs of all the transcriptions they create. That way a developer can, at any time, query the AssemblyAI API for the details of a historical transcription with a GET request like below:

GET /v2/transcript/{transcript_id}

But over time we’ve found that storing these transcription IDs may not always be easy for developers, as it often requires a schema change to a database which is never fun. More commonly, developers integrating the AssemblyAI API want to be able to query for a list of transcriptions that are still processing, failed, or queued, to help them debug their applications as they are building.

That’s why today we are happy to make available our new List Endpoint, which give developers the ability to query for, and paginate through, all of their historical transcriptions. For example, here’s how we can quickly query for the most recent 200 completed transcriptions on our account:

curl --request GET \
--url https://api.assemblyai.com/v2/transcript?limit=200&status=completed \
--header 'authorization: YOUR-ASSEMBLYAI-TOKEN' \
--header 'content-type: application/json'

The above query will return a JSON response like this:

{
    "transcripts": [
         {
            "id": "3hg73t53o-fb8f-437c-9c5f-f852dc9b859b",
            "resource_url": "https://api.assemblyai.com/v2/transcript/3hg73t53o-fb8f-437c-9c5f-f852dc9b859b",
            "status": "completed",
            "created": "2021-05-04T23:30:03.272084",
            "completed": "2021-05-04T23:31:00.918176",
            "audio_url": "https://cdn.assemblyai.com/upload/60e31fd4-1f90-49d9-abb2-6d60433020a6"
        },
        {
            "id": "3t05k0dqa-3fe9-4dc5-bd93-985765402323",
            "resource_url": "https://api.assemblyai.com/v2/transcript/3t05k0dqa-3fe9-4dc5-bd93-985765402323",
            "status": "completed",
            "created": "2021-05-03T19:38:53.567626",
            "completed": "2021-05-03T19:39:21.827162",
            "audio_url": "https://cdn.assemblyai.com/upload/730b9ca0-1029-4519-9697-9c0e96123bc0"
        },
        {
            "id": "8w5chxgaz-dcf5-4647-8cb4-cdfeaccdaa7d",
            "resource_url": "https://api.assemblyai.com/v2/transcript/8w5chxgaz-dcf5-4647-8cb4-cdfeaccdaa7d",
            "status": "completed",
            "created": "2021-05-03T19:38:06.985813",
            "completed": "2021-05-03T19:38:31.671583",
            "audio_url": "https://cdn.assemblyai.com/upload/730b9ca0-1029-4519-9697-9c0e96123bc0"
        }
        ...
    ],
    "page_details": {
        "limit": 200,
        "result_count": 200,
        "current_url": "https://api.assemblyai.com/v2/transcript?limit=200&status=completed",
        "prev_url": "https://api.assemblyai.com/v2/transcript?limit=200&status=completed&before_id=8w5chxgaz-dcf5-4647-8cb4-cdfeaccdaa7d",
        "next_url": "https://api.assemblyai.com/v2/transcript?limit=200&status=completed&after_id=3hg73t53o-fb8f-437c-9c5f-f852dc9b859b"
    },
}    

As you can see above, the API returns a list of our most recent completed transcripts. The API only returns up to 200 transcriptions in the API response, so you can easily make iterative GET requests to the prev_url or next_url in the page_details section of the JSON response to “iterate” to the next “page” of transcriptions, giving you the ability to paginate through all of the transcriptions in your account. You can also filter the results by status, to query for only your “processing” transcriptions, for example. 

For more details on this new API endpoint, check out the API Docs here - and if you have any questions at all, just let us know! You can email support@assemblyai.com any time, and you can also use the chat in the bottom right corner of the page to chat live with our support team! 

Subscribe to our blog!

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

You may also like

Checkout some of our recent research and product updates

How to Convert an MP3 File to Text with an API
Tutorials
How to Convert an MP3 File to Text with an API

how to convert an mp3 file to text with an API

Is Word Error Rate a Good Measure of Speech Recognition Systems?
Deep Learning
Is Word Error Rate a Good Measure of Speech Recognition Systems?

What is Word Error Rate? Word Error Rate is a measure of how accurate an Automatic Speech Recognition (ASR) system performs. Quite literally, it calculates how many “errors” are in the transcription text produced by an ASR system, compared to a human transcription.

The State of Python Speech Recognition in 2021
Tutorials
The State of Python Speech Recognition in 2021

The State of Python Speech Recognition in 2021

build with assemblyai

Accurately convert your audio and video files to text with AssemblyAI's Speech-to-Text API