Requires
read_dataaccess 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
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
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 |