Listing all historical transcripts

    With the list endpoint, you can retrieve a list of all the transcripts you have created. This list can also be filtered by the transcript status.

    How to query the list endpoint

    To get a list of the 200 most recently completed transcripts you can make a GET request to the following endpoint.

    https://api.assemblyai.com/v2/transcript?limit=200&status=completed

    A quick curl example of this is shown below.

    curl --request GET \
    --url https://api.assemblyai.com/v2/transcript?limit=200&status=completed \
    --header 'authorization: YOUR-ASSEMBLYAI-TOKEN' \
    --header 'content-type: application/json'
    Query Description Constraints Optional
    limit Max results to return in a single response Between 1 and 200 (defaults to 10) Yes
    status Filter by transcript status Must be "queued", "processing", "completed", or "error" Yes

    In the above curl statement, we are querying for the most recent 200 transcripts with the status of "completed". This GET request 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"
        },
    }    

    The above response contains two top-level keys, they are transcripts and page_details.

    The transcripts key will contain an array of objects (your list of transcripts), with each object containing the following information:

    key value
    id ID of the transcript
    resource_url Make a GET request to this URL to get the complete information for this transcript
    status The current status of the transcript
    created The date and time the transcript was created
    completed The date and time your transcript finished processing
    audio_url The audio_url that was submitted in your initial POST request when creating a transcript

    Since the API only returns a maximum of 200 transcripts per response, it treats each response as a "page" of results. The page_details key will give you information about the current "page" you are on, and how to navigate to the next "page" of results.

    Paginate through multiple lists of transcripts (useful if looking for more than the limit)

    To navigate to the next "page" of results, you will want to grab the value of prev_url in the page_details object from your initial GET request. You can then make the same API call as before, replacing the endpoint with the value of prev_url. You can continue to do this until prev_url is null, meaning you have pulled all your transcripts from the API!

    Transcripts are listed from newest to oldest, so prev_url will always point to the prior "page" of older transcripts.

    Here is our curl request from earlier:

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

    Once we have the response, we can make our subsequent request below using the value of prev_url:

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

    You can continue to do this until the value of prev_url is null, meaning you have successfully retrieved all transcripts in your account!

    Advanced filter parameters

    When making a GET request to list transcripts, you can include any of the following parameters with your GET request to further filter the results you get back.

    Query Description Constraints Optional
    limit Max results to return in a single response Between 1 and 200 (inclusive with a default value of 10) Yes
    status Filter by transcript status Must be queued, processing, completed, or error Yes
    created_on Only return transcripts created on this date Format: YYYY-MM-DD Yes
    before_id Return transcripts that were created before this id Valid transcript id Yes
    after_id return transcripts that were created after this id Valid transcript id Yes
    throttled_only Only return throttled transcripts, overrides status filter Boolean; true or false Yes

    For any questions, please reach out to support@assemblyai.com or use the chat in the bottom right of this page!