Get Annotation Set Automatic Speech Recognition (ASR) Contents API

Call this API to download the annotation set contents in text/csv or application/json format.

HTTP method and path

GET v1/skills/{skillId}/asrAnnotationSets/{annotationSetId}/annotations?maxResults={maxResults}&nextToken={nextToken}
Attributes Type Description Required
skillId String Skill Id as part of the URI path. Yes
annotationSetId String Annotation set Id as part of the request URI path. Yes
maxResults Integer Query parameter for indicating the maximum number of results to return. Default is 1000. The server might limit the number to fewer results than the specified maxResults value. No
nextToken String Query parameter for indicating continuation token. No

Request

Request headers

Accept: [text/csv, application/json]
Attributes Type Description Required
Accept String Request header indicating what content type the client accepts as response. Possible values are text/csv – Returns annotation set contents in CSV format and application/json – Returns annotation set contents in JSON format. Yes

Request body

None.

Response

HTTP status

HTTP 200 OK

Response headers

Content-Type: [text/csv, application/json]

Response body

Content-Type: application/json

{
    "paginationContext": {
        "nextToken": string
    },
    "annotations": [{
        "uploadId": string,
        "filePathInUpload": string,
        "evaluationWeight": integer,
        "expectedTranscription": string,
        "audioAsset": {
            "downloadUrl": string,
            "expiryTime": string
        }
    }]
}
Attributes Type Description Required
annotations[i] Object Annotation object. Valid values are uploadId, filePathInUpload, evaluationWeight, expectedTranscription, and audioAsset. Yes
audioAsset Object Object containing information about downloading audio. Present when uploadId and filePathInUpload are available. No
audioAsset.downloadUrl String Pre-signed download URL for downloading the audio file. Required when audioAsset is present.
audioAsset.expiryTime String Timestamp for the audio download URL expiration date in ISO 8601 format. Required when audioAsset is present.
paginationContext Object Object containing pagination information. If present, the response contains incomplete annotationSets. If omitted, all annotationSets were already returned. No
paginationContext.nextToken String Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of annotations.

Content-Type: text/csv

uploadId,filePathInUpload,evaluationWeight,expectedTranscription,audioAssetDownloadUrl,audioAssetDownloadUrlExpiryTime
string,string,integer,string,string,string
Attributes Type Description Required
uploadId String Upload Id returned when you create an upload using the Catalog API. Must be present when expectedTranscription is missing. When uploadId is present, filePathInUpload must also be present.
filePathInUpload String Path in the uploaded zip file. For example, consider a zip file containing a folder named 'folder' and with an audio file named audio.mp3 in that folder. The path is folder/audio.mp3. Use a forward slash ('/') to concatenate directories. Yes
evaluationWeight Integer Weight of the test case in an evaluation. Use this value for calculating metrics, such as OVERALL_ERROR_RATE. Acceptable values are from 1 through 1000, from least to most significant. Yes
expectedTranscription String Expected transcription text for the input audio. The acceptable length of the string is between 1 and 500 Unicode characters. Yes
audioAssetDownloadUrl String URL for downloading the audio. Yes
audioAssetDownloadUrlExpiryTime String Timestamp for when the download URL expires in ISO - 8601 format. Yes

Error response

The following table lists call-specific errors. For a reference of errors that can apply to all ASR APIs, see Automatic Speech Recognition (ASR) API Error Reference.

HTTP Status Code Error Code Scenario

404 Not Found

RESOURCE_NOT_FOUND

Requested skill cannot be found.

Requested annotation set cannot be found.

400 Bad Request

INVALID_REQUEST_PARAMETER

AnnotationSetId is malformed.

Value of nextToken is invalid.
INAVLID_INTEGER_VALUE Value of maxResults query parameter is not within the allowed range.

MISSING_REQUIRED_PROPERTY

Accept header is missing.

INVALID_ENUM_VALUE

The value in the Accept header is not accepted.
PARAMETER_EXPIRED nextToken is expired.

500 Internal Server Error

INTERNAL_SERVER_ERROR

Request failed due to an internal server error.

Examples

Sample Request Sample Response
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1 Accept: text/csv HTTP 200 OK Content-Type: text/csv filePathInUpload,uploadId,evaluationWeight,expectedTranscription,audioAssetDownloadUrl,audioAssetDownloadUrlExpiryTime hello_world.mp3,amazn.catalog.upid.12341234,5,alexa hello world, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ ask say hello.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA,2020-04-013 13:23PM TZ ask say hello.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ something.wav,amazn.catalog.upid.12341234,10,ask hello world skill say hello, https://audio.s3.amazon.com/XXXYYYA, 2020-04-013 13:23PM TZ
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1 Accept: application/json
HTTP 200 OK Content-Type: application/json { "annotations":[ { "uploadId": "1234-12314-12314", "filePathInUpload":"hello_world.mp3", "evaluationWeight":5, "expectedTranscription":"alexa hello world", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } }, { "uploadId":"1234-12314-12315", "filePathInUpload":"ask say hello.wav", "evaluationWeight":10, "expectedTranscription":"ask hello world skill say hello", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } }, { "uploadId": "1234-12314-12348", "filePathInUpload":"ask say hello.wav", "evaluationWeight":10, "expectedTranscription":"ask hello world skill say hello", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } }, { "uploadId": "1234-12314-12348", "filePathInUpload":"something.wav", "evaluationWeight":10, "expectedTranscription":"ask hello world skill say hello", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } } ] }
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations?maxResults=1 HTTP/1.1 Accept: application/json
HTTP 200 OK Content-Type: application/json { "paginationContext": { "nextToken": "1234" }, "annotations":[ { "uploadId": "1234-12314-12314", "filePathInUpload":"hello_world.mp3", "evaluationWeight":5, "expectedTranscription":"alexa hello world", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-12 10:23:32AM" } } ] }
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations?maxResults=1?nextToken=1234 HTTP/1.1 Accept: application/json
HTTP 200 OK Content-Type: application/json { "paginationContext": { "nextToken": "2345" }, "annotations":[ { "uploadId": "1234-12314-12315", "filePathInUpload":"hello_alexa.mp3", "evaluationWeight":5, "expectedTranscription":"alexa hello world", "audioAsset": { "downloadUrl": "https://s3.amazon.com/asdfasdfasdf/fasdf", "expiryTime": "2019-10-13 10:23:32AM" } } ] }
GET /v1/skills/1234/asrAnnotationSets/1234-1234-12341234/annotations HTTP/1.1 Accept: application/json
HTTP 400 Bad Request Content-Type: application/json { "message": "Annotation set not found", "violations": [{ "message": "Annotation set identified by 1234-1234-12341234 cannot be found", "code": "RESOURCE_NOT_FOUND" }] }