POST
https://api.nexscope.ai/amazonAds/reporting/reportsRun this API
Send a JSON request to execute this API and receive the documented response payload.
Endpoint
| Method | POST |
| Path | https://api.nexscope.ai/amazonAds/reporting/reports |
| Auth | Bearer API key |
| Content-Type | application/json |
Request parameters
| Name | Type | Required | Description |
|---|---|---|---|
connectionId | integer | required | An Amazon Ads connection owned by the authenticated Nexscope user. |
reportTypeId | string | required | Check the corresponding report-types file. |
adProduct | string | required | Contrast report-type frontmatter, such as `SPONSORED_PRODUCTS`, `SPONSORED_BRANDS`, `SPONSORED_DISPLAY`. |
groupBy | array | required | Compare report-type frontmatter; no guesswork required. |
columns | array | required | Check against a subset of allowed columns of the corresponding Base metrics table. |
startDate | string | required | `YYYY-MM-DD`, including the current day. |
endDate | string | required | `YYYY-MM-DD`, including the current day. |
name | string | optional | Report display name. |
timeUnit | string | optional | `DAILY` or `SUMMARY`. Example: SUMMARY |
format | string | optional | Report file format. Example: GZIP_JSON |
filters | array | optional | Field and value enumerations are based on the corresponding report-type file. |
pollInterval | integer | optional | Polling interval in seconds. Example: 30 |
maxAttempts | integer | optional | Maximum number of polls, default waiting window of approximately 10 minutes. Example: 20 |
skipDepCheck | boolean | optional | Skip dependency checking. Example: false |
serveExtractedFileHttp | boolean | optional | Whether to start the native temporary HTTP service. Example: true |
serveHost | string | optional | Native service binding address. |
servePort | integer | optional | 0 indicates the system allocated port. Example: 0 |
serveSeconds | integer | optional | The number of seconds the local link remains alive. Example: 300 |
includeAmazonSourceUrl | boolean | optional | Whether to return the Amazon presigned source URL. Example: false |
confirmationToken | string | optional | For mutations, first preview without a token, then confirm using the returned single-use token. |
Code example
{
"body": "{\"reportTypeId\":\"spCampaigns\"}",
"contentType": "application/vnd.createasyncreportrequest.v3+json",
"method": "POST"
}Response example
Platform response envelope. code 0 indicates success or acceptance; data contains the business result.
{
"code": 0,
"cost": "-1",
"data": {},
"msg": null,
"time": "2026-01-01 00:00:00",
"traceId": null,
"ts": "0"
}Response fields
Response field reference (12 fields)
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | optional | Whether downloaded and decompressed successfully. |
reportId | string | optional | Amazon reporting ID. |
status | string | optional | `PENDING`, `PROCESSING`, `COMPLETED` or `FAILED`. |
reportTypeId | string | optional | The type of report requested. |
pollAttempts | integer | optional | Number of times polled. |
elapsedSeconds | number | optional | The number of seconds elapsed. |
downloadPath | string | optional | The downloaded or decompressed local file path. |
extractedFileHttpUrl | string | optional | Native temporary file URL (if enabled). |
serveExpiresAt | string | optional | Native URL expiration time (if returned). |
failureReason | string | optional | Reason for upstream failure when `FAILED`. |
resumeHint.mode | string | optional | `poll-only`。 |
resumeHint.params | object | optional | Reuse the same reportId and increase maxAttempts to continue polling. |
Responses
| Code | Description |
|---|---|
| 200 | HTTP request completed. Check JSON code; only 0 indicates business success or acceptance. |
| 400 | Request JSON or required API parameters are invalid. |
| 401 | API key is missing, invalid, or cannot be matched to a user. |
| 5xx | API execution or upstream service failed. |
Data source, freshness, and limitations
Source, freshness, coverage, rate limits, and estimation notes are not specified in this API definition unless they appear in the request or response field documentation above. Do not assume official marketplace data or real-time freshness when it is not explicitly documented.