🔒
Requires read_data access scope.

Create a data query task to initiate an asynchronous query task, which will return upon completion with the task's ID. The asynchronous task queries based on the event, beginTime, and endTime, and updates the processing results in the Task information. You can obtain the current task processing status through data detail API. Please note that due to the long duration of the asynchronous query, it does not guarantee that the query results will be available when you retrieve the task details. If the task processing fails, you will need to create a new task.

The Create Data Query Task API is used to initiate an asynchronous query task, which returns a unique query_id upon initiation. The asynchronous task processes data based on the specified event type, start time (beginTime), and end time (endTime). This API allows querying large data sets over a specific time range for further analysis.

This API is especially useful for:

Fetching event data for analytics and reporting.
Tracking specific user interactions, such as purchases or cart additions.
Handling data-intensive queries asynchronously to improve performance.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Query Parameters

Name	Type	Required	Description	Example
`event`	`string`	Yes	Event type to query. Supported types: `impressions`, `add_payment_info`, `add_to_cart`, `begin_checkout`, `pageview`, `place_order`, `product_search`, `product_view`, `purchase_product`, `refund_order`. If not provided, all event types except `impressions` are queried.	`add_to_cart`
`beginTime`	`string`	Yes	Start time for the query in ISO 8601 format. Only events after this time are queried.	`2020-12-30T15:04:05`
`endTime`	`string`	Yes	End time for the query in ISO 8601 format. The duration between `beginTime` and `endTime` cannot exceed 24 hours.	`2020-12-30T16:04:05`

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Success Response

Field	Type	Description	Example
`query_id`	`string`	The unique identifier for the created query task.	`7ce94c64-c42d-4e79-ae97-8b89e1f5cc8b`

Error Response

Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.

Field	Type	Example	Description
`errors`	Array	`[ "file number error"]`	A list of errors encountered during the request processing.

Field	Type	Example	Description
`error`	String	`"page not found"`	Indicates an error encountered during the process

Error Detail

Status Code	Message	Possible Reason	Example Response
400	Bad Request	Invalid input format or request structure (e.g., missing required fields or incorrect data types).	`Bad Request`
	Unauthorized	The request is missing valid authentication credentials or the credentials provided are invalid.	`Unauthorized`

API Structure Overview

200OK