Data Kiosk API v2023-11-15 Reference
Submit GraphQL queries from a variety of schemas.
Overview
The Selling Partner API for Data Kiosk lets you submit GraphQL queries from a variety of schemas to help selling partners manage their businesses.
Version information
Version : 2023-11-15
Contact information
Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html
License information
License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
URI scheme
Host : sellingpartnerapi-na.amazon.com
BasePath : /
Schemes : HTTPS
Consumes
application/json
Produces
application/json
Operations
getQueries
createQuery
getQuery
cancelQuery
getDocument
Paths
GET /dataKiosk/2023-11-15/queries
Operation: getQueries
Description
Returns details for the Data Kiosk queries that match the specified filters. See the createQuery operation for details about query retention.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 0.0222 | 10 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
| Query | processingStatuses optional | A list of processing statuses used to filter queries. Min count : 1 | < enum (ProcessingStatuses) > array | - |
| Query | pageSize optional | The maximum number of queries to return in a single call. Minimum : 1 Maximum : 100 | integer | 10 |
| Query | createdSince optional | The earliest query creation date and time for queries to include in the response, in ISO 8601 date time format. The default is 90 days ago. | string (date-time) | - |
| Query | createdUntil optional | The latest query creation date and time for queries to include in the response, in ISO 8601 date time format. The default is the time of the getQueries request. | string (date-time) | - |
| Query | paginationToken optional | A token to fetch a certain page of results when there are multiple pages of results available. The value of this token is fetched from the pagination.nextToken field returned in the GetQueriesResponse object. All other parameters must be provided with the same values that were provided with the request that generated this token, with the exception of pageSize which can be modified between calls to getQueries. In the absence of this token value, getQueries returns the first page of results. | string | - |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | GetQueriesResponse |
For error status codes, descriptions and schemas, see Error responses and schemas.
POST /dataKiosk/2023-11-15/queries
Operation: createQuery
Description
Creates a Data Kiosk query request.
Note: The retention of a query varies based on the fields requested. Each field within a schema is annotated with a @resultRetention directive that defines how long a query containing that field will be retained. When a query contains multiple fields with different retentions, the shortest (minimum) retention is applied. The retention of a query's resulting documents always matches the retention of the query.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 0.0167 | 15 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | body required | The body of the request. | CreateQuerySpecification |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 202 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | CreateQueryResponse |
For error status codes, descriptions and schemas, see Error responses and schemas.
GET /dataKiosk/2023-11-15/queries/{queryId}
Operation: getQuery
Description
Returns query details for the query specified by the queryId parameter. See the createQuery operation for details about query retention.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 2.0 | 15 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Path | queryId required | The query identifier. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | Query |
For error status codes, descriptions and schemas, see Error responses and schemas.
DELETE /dataKiosk/2023-11-15/queries/{queryId}
Operation: cancelQuery
Description
Cancels the query specified by the queryId parameter. Only queries with a non-terminal processingStatus (IN_QUEUE, IN_PROGRESS) can be cancelled. Cancelling a query that already has a processingStatus of CANCELLED will no-op. Cancelled queries are returned in subsequent calls to the getQuery and getQueries operations.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 0.0222 | 10 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Path | queryId required | The identifier for the query. This identifier is unique only in combination with a selling partner account ID. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 204 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | No Content |
For error status codes, descriptions and schemas, see Error responses and schemas.
GET /dataKiosk/2023-11-15/documents/{documentId}
Operation: getDocument
Description
Returns the information required for retrieving a Data Kiosk document's contents. See the createQuery operation for details about document retention.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 0.0167 | 15 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Path | documentId required | The identifier for the Data Kiosk document. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | GetDocumentResponse |
For error status codes, descriptions and schemas, see Error responses and schemas.
Error Responses and Schemas
This table contains HTTP status codes and associated information for error responses.
| HTTP Code | Description | Schema |
|---|---|---|
| 400 | Request has missing or invalid parameters and cannot be parsed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 404 | The resource specified does not exist. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 413 | The request size exceeded the maximum accepted size. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 415 | The request payload is in an unsupported format. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 429 | The frequency of requests was greater than allowed. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 503 | Temporary overloading or maintenance of the server. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
Definitions
ErrorList
A list of error responses returned when a request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| errors required | Error response returned when the request is unsuccessful. | < Error > array |
Error
Error response returned when the request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| code required | An error code that identifies the type of error that occurred. | string |
| message required | A message that describes the error condition. | string |
| details optional | Additional details that can help the caller understand or fix the issue. | string |
Query
Detailed information about the query.
| Name | Description | Schema |
|---|---|---|
| queryId required | The query identifier. This identifier is unique only in combination with a selling partner account ID. | string |
| query required | The submitted query. | string |
| createdTime required | The date and time when the query was created, in ISO 8601 date time format. | string (date-time) |
| processingStatus required | The processing status of the query. | enum (ProcessingStatus) |
| processingStartTime optional | The date and time when the query processing started, in ISO 8601 date time format. | string (date-time) |
| processingEndTime optional | The date and time when the query processing completed, in ISO 8601 date time format. | string (date-time) |
| dataDocumentId optional | The data document identifier. This identifier is only present when there is data available as a result of the query. This identifier is unique only in combination with a selling partner account ID. Pass this identifier into the getDocument operation to get the information required to retrieve the data document's contents. | string |
| errorDocumentId optional | The error document identifier. This identifier is only present when an error occurs during query processing. This identifier is unique only in combination with a selling partner account ID. Pass this identifier into the getDocument operation to get the information required to retrieve the error document's contents. | string |
| pagination optional | When a query produces results that are not included in the data document, pagination occurs. This means the results are divided into pages. To retrieve the next page, you must pass a CreateQuerySpecification object with paginationToken set to this object's nextToken and with query set to this object's query in the subsequent createQuery request. When there are no more pages to fetch, the nextToken field will be absent. | pagination |
| Name | Description | Schema |
|---|---|---|
| nextToken optional | A token that can be used to fetch the next page of results. | string |
QueryList
A list of queries.
Type : < Query > array
CreateQuerySpecification
Information required to create the query.
| Name | Description | Schema |
|---|---|---|
| query required | The GraphQL query to submit. A query must be at most 8000 characters after unnecessary whitespace is removed. | string |
| paginationToken optional | A token to fetch a certain page of query results when there are multiple pages of query results available. The value of this token must be fetched from the pagination.nextToken field of the Query object, and the query field for this object must also be set to the query field of the same Query object. A Query object can be retrieved from either the getQueries or getQuery operation. In the absence of this token value, the first page of query results will be requested. | string |
CreateQueryResponse
The response for the createQuery operation.
| Name | Description | Schema |
|---|---|---|
| queryId required | The identifier for the query. This identifier is unique only in combination with a selling partner account ID. | string |
GetQueriesResponse
The response for the getQueries operation.
| Name | Description | Schema |
|---|---|---|
| queries required | The Data Kiosk queries. | QueryList |
| pagination optional | When a request has results that are not included in this response, pagination occurs. This means the results are divided into pages. To retrieve the next page, you must pass the nextToken as the paginationToken query parameter in the subsequent getQueries request. All other parameters must be provided with the same values that were provided with the request that generated this token, with the exception of pageSize which can be modified between calls to getQueries. When there are no more pages to fetch, the nextToken field will be absent. | pagination |
| Name | Description | Schema |
|---|---|---|
| nextToken optional | A token that can be used to fetch the next page of results. | string |
GetDocumentResponse
The response for the getDocument operation.
| Name | Description | Schema |
|---|---|---|
| documentId required | The identifier for the Data Kiosk document. This identifier is unique only in combination with a selling partner account ID. | string |
| documentUrl required | A presigned URL that can be used to retrieve the Data Kiosk document. This URL expires after 5 minutes. If the Data Kiosk document is compressed, the Content-Encoding header will indicate the compression algorithm.Note: Most HTTP clients are capable of automatically decompressing downloaded files based on the Content-Encoding header. | string |
ProcessingStatuses
Type : enum
| Value | Description |
|---|---|
| CANCELLED | The query was cancelled before it began processing. |
| DONE | The query has completed processing. |
| FATAL | The query was aborted due to a fatal error. |
| IN_PROGRESS | The query is being processed. |
| IN_QUEUE | The query has not yet started processing. It may be waiting for another IN_PROGRESS query. |
ProcessingStatus
The processing status of the query.
Type : enum
| Value | Description |
|---|---|
| CANCELLED | The query was cancelled before it began processing. |
| DONE | The query has completed processing. |
| FATAL | The query was aborted due to a fatal error. |
| IN_PROGRESS | The query is being processed. |
| IN_QUEUE | The query has not yet started processing. It may be waiting for another IN_PROGRESS query. |
Updated 5 months ago