A New API Endpoint to Paginate Through Historical Transcripts

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!