HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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.022210

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

TypeNameDescriptionSchemaDefault
QueryprocessingStatuses
optional
A list of processing statuses used to filter queries.
Min count : 1
< enum (ProcessingStatuses) > array-
QuerypageSize
optional
The maximum number of queries to return in a single call.
Minimum : 1
Maximum : 100
integer10
QuerycreatedSince
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)-
QuerycreatedUntil
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)-
QuerypaginationToken
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 CodeDescriptionSchema
200Success.
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.016715

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

TypeNameDescriptionSchema
Bodybody
required
The body of the request.CreateQuerySpecification

Responses

HTTP CodeDescriptionSchema
202Success.
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.015

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

TypeNameDescriptionSchema
PathqueryId
required
The query identifier.string

Responses

HTTP CodeDescriptionSchema
200Success.
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.022210

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

TypeNameDescriptionSchema
PathqueryId
required
The identifier for the query. This identifier is unique only in combination with a selling partner account ID.string

Responses

HTTP CodeDescriptionSchema
204Success.
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.016715

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

TypeNameDescriptionSchema
PathdocumentId
required
The identifier for the Data Kiosk document.string

Responses

HTTP CodeDescriptionSchema
200Success.
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 CodeDescriptionSchema
400Request 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
403Indicates 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
404The 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
413The request size exceeded the maximum accepted size.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
415The request payload is in an unsupported format.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
429The frequency of requests was greater than allowed.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
503Temporary 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.

NameDescriptionSchema
errors
required
Error response returned when the request is unsuccessful.< Error > array

Error

Error response returned when the request is unsuccessful.

NameDescriptionSchema
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.

NameDescriptionSchema
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


pagination

NameDescriptionSchema
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.

NameDescriptionSchema
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.

NameDescriptionSchema
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.

NameDescriptionSchema
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


pagination

NameDescriptionSchema
nextToken
optional
A token that can be used to fetch the next page of results.string

GetDocumentResponse

The response for the getDocument operation.

NameDescriptionSchema
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

ValueDescription
CANCELLEDThe query was cancelled before it began processing.
DONEThe query has completed processing.
FATALThe query was aborted due to a fatal error.
IN_PROGRESSThe query is being processed.
IN_QUEUEThe query has not yet started processing. It may be waiting for another IN_PROGRESS query.

ProcessingStatus

The processing status of the query.

Type : enum

ValueDescription
CANCELLEDThe query was cancelled before it began processing.
DONEThe query has completed processing.
FATALThe query was aborted due to a fatal error.
IN_PROGRESSThe query is being processed.
IN_QUEUEThe query has not yet started processing. It may be waiting for another IN_PROGRESS query.