Progressive Response REST API Reference

Use the Progressive Response REST API to send an interim response for Alexa to play until your skill sends the full response. Progressive responses might include confirmation that your skill is processing the answer, such as "Please wait while I look that up for you …."

For more details about progressive responses, see Send the User a Progressive Response.

API endpoint

Use one of the following API hosts, based on the region where the customer is located:

  • North America:
  • Europe:
  • Far East:

You can find the API endpoint in the context.System.apiEndpoint retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.


Each API request must have an authorization header whose value is the context.System.apiAccessToken retrieved from a request from Alexa, such as the LaunchRequest or IntentRequest.


The Progressive Response API includes the following operations.

Operation HTTP method and URI

Send directive

POST /v1/directives

Send directive

Send a directive to instruct Alexa to speak the provided text, generated with Speech Synthesis Markup Language (SSML).


To send a directive, you make a POST request to the /v1/directives resource.

Request path and header example

Copied to clipboard.

POST /v1/directives
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

access token


Access token used for the customer. Set to request.context.System.apiAccessToken from the LaunchRequest or IntentRequest.



Request body example

Copied to clipboard.

    "header": {
        "requestId": "amzn1.echo-api.request.1"
    "directive": {
        "type": "VoicePlayer.Speak",
        "speech": "<speak>This text is spoken while your skill processes the full response.</speak>"

Request body properties

Property Description Type Required


Identifies the specific request sent from Alexa to your skill.




Unique ID for the request.
Set to request.requestId from the LaunchRequest or IntentRequest.




Defines the directive to send to Alexa.




Type of directive.
Valid value: VoicePlayer.Speak.




Text for spoken content, wrapped in SSML <speak> tags.
Valid for VoicePlayer.Speak only.
You can use other SSML tags within the <speak> tags with the following limits:

  • The maximum text size is 600 characters. This value is smaller than the outputSpeech property.
  • You must wrap the text in <speak> tags, even if you don't use any other SSML tags within the string.
  • If you use the SSML <audio> tag, the maximum audio length is 30 seconds. This value is shorter than the normal audio allowed in this tag. For additional MP3 requirements, see <audio>.




A successful response returns HTTP 204 No Content to indicate that Alexa processed the request successfully. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. An error status code indicates that Alexa didn't speak the text.

If a properly formed request fails, you can safely resend it to retry. Alexa doesn't play the same content multiple times.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status Description

204 No Content

Alexa processed the progressive response successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid, such as a missing or invalid requestId.

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, the requestId represents a request that's no longer applicable, such as after the skill sends the full response.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Was this page helpful?

Last updated: frontmatter-missing