Analytics API

Generate Report

POST /v1/enterprise/analytics/reports

US, CA

US, CA

US, CA

US, CA

access token

Header

LWA token.

String

Yes

unitId

Directed ID of a unit in the hierarchy in the format amzn1.alexa.unit.did.xxxx. This is the root unit of the report. This means that the report includes data for the specified unit and its descendants. Max length of 255 characters.

String

Yes

categories

An array of enumerations that specify the type of data to deliver in the report.
Accepted values: PROPERTY_SKILL, PROACTIVE_CAMPAIGN, DOMAIN_ENGAGEMENT, COMMUNICATION, DEVICE.

Array of enumeration values

Yes

dateRange

Encapsulates information about the dates the report should cover.

Object

Yes

dateRange.startDate

The earliest date to retrieve data for, inclusive, in the format YYYY-MM-DD. Date can be no more than 93 days before the current date. The date you provide follows UTC+00:00 date stamps.

String

Yes

dateRange.endDate

The latest date to retrieve data for, inclusive, in the format YYYY-MM-DD. Date must be at least four days before the current date. The date you provide follows UTC+00:00 date stamps.

String

Yes

dateRange.granularity

Indicates whether to roll up the data for the specified time range.
Accepted values:

• RANGE – Roll up the data into a single count.
• DAILY – Display data for each day. Days are derived from startDate and endDate.

For example, assume the report contains three days of data for two units (unitA, unitB) measuring some metric with a value of 1 each day:

• For DAILY, the report has six rows (unitAday1=1, unitAday2=1, unitAday3=1, unitBday1=1, unitBday2=1, unitBday3=1)
• For RANGE, the report has two rows (unitA=3, unitB=3)

Enumeration: RANGE or DAILY

Yes

format

The output file type for the report.
Accepted values: CSV.

Enumeration: CSV

Yes

showSubUnits

When true, the report includes a row for each descendent in the hierarchy. When false, the report displays all data in one count for the provided unit.

For example, assume the report contains two days of data for three units in a tree structure with unitA as the parent of unitB and unitC. In this example, the metric being measured has a value of 1 for each unit each day.

• When showSubUnits is true, the report has six rows (unitAday1=1, unitBday1=1, unitCday1=1, unitAday2=1, unitBday2=1, unitCday2=1).
• When showSubUnits is false, the report has two rows (unitAday1=3, unitAday2=3). The metrics for unitB and unitC are included in the count for unitA.

Boolean

Yes

deliveryChannel

Encapsulates information about how to deliver the output report.

Object

Yes

deliveryChannel.type

Specifies to deliver the report.
Accepted values: S3.

Enumeration: S3

Yes

deliveryChannel.id

Identifier for the output report delivery location. Max length of 255 characters. When type is S3, set id to the ARN for the S3 bucket in the format arn:aws:s3:::<bucket id>.

String

No

Content-Type

Contains application/json

String

X-Amzn-RequestId

A UUID generated for the individual request.

String

message

A generic success or failure message

String

reports[]

An array of objects with information about the expected output reports. If an error occurs, the reports array is empty.

Array

reports[i].category

Name of the corresponding category for this report.

String

reports[i].name

Name of an output report. Reports are generated asynchronously based on the request.

String

errors[]

Array of problems encountered during processing. Included when an error occurs.

Array

errors[i].errorDescription

A short message explaining the error.

String

errors[i].errorCode

An ID to reference documentation for more information about the error.

String

errors[i].status

HTTP Response code for the type of error encountered.

int

202 Accepted

The request was successful. Reports are generated asynchronously and are available at the specified deliveryChannel when complete. The specific reports to generate are specified in the reports array in the response body. For details, see Response body properties.

400 Bad Request

Indicates that one or more properties in the request body aren't valid. The following example shows the response body with the error and message.

{
  "errors": [
    {
      "errorCode": "BAD_REQUEST",
      "errorDescription": "Granularity format Invalid",
      "status": 400
    }
  ],
  "message": "There was an error processing the request",
  "reports": []
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

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

API exceeded the permitted rate limit or specified number of requests per unit of time. Requests can be retried using exponential back-off.

500 Server Error

Error occurred on the server. The request can be retried using exponential back-off.

503 Service Unavailable

Data not yet available due to an upstream processing delay. Amazon recommends that you retry every few hours while we work to resolve the delay.

503 Service Unavailable

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