> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Maestro Task Query API Integration Guide

> Maestro AI Video Studio integration guide - Ace Data Cloud

The main function of the Maestro Task Query API is to query the execution status and final result of a task through the task ID returned by the [Maestro Video Generation API](/en/guides/maestro/maestro_videos) (`POST /maestro/videos`).

This document will provide a detailed introduction to the integration guide for the Maestro Task Query API. Since video generation is an asynchronous task, after submission, you need to use this API to poll for progress and completed videos. **Polling is free and does not consume credits.**

`POST https://api.acedata.cloud/maestro/tasks`

## Application Process

To use the Maestro Task Query API, first go to the [Ace Data Cloud Console](https://platform.acedata.cloud/console/applications) to obtain your API Token and keep it for later use.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

If you have not yet logged in or registered, you will be automatically redirected to the login page to register and log in, and will automatically return to the current page after completion.

**One API Token can call all platform services; there is no need to apply separately for each service.** Your first application will include free credits for a free trial; when credits are insufficient, you can top up your general balance in the [console](https://platform.acedata.cloud/console/coin).

> 📘 Full documentation: [Maestro Task Query API →](https://platform.acedata.cloud/documents/maestro-tasks)

## Query a Single Task

For how to create a video task, please refer to the [Maestro Video Generation API](/en/guides/maestro/maestro_videos) documentation. We use one of the task IDs it returns as an example: `f57e99c4f60f4373a15517742ce2357d`, to demonstrate how to query its status and result.

### Set Request Headers and Request Body

**Request Headers** include:

* `accept`: Specifies that JSON-formatted response results are accepted; fill in `application/json` here.
* `authorization`: The key for calling the API, which can be directly selected from the dropdown after application.
* `content-type`: The format of the request body; fill in `application/json` here.

**Request Body** includes:

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | string | Required when querying a single task | The `task_id` returned by `POST /maestro/videos` |
| `action` | string | No | `retrieve` (default, query a single task); fixed as `retrieve_batch` when querying the history list |

### Code Examples

The corresponding CURL code is as follows:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "action": "retrieve"
}'
```

The corresponding Python code is as follows:

```python theme={null}
import requests

url = "https://api.acedata.cloud/maestro/tasks"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "id": "f57e99c4f60f4373a15517742ce2357d",
    "action": "retrieve"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

### Response Example

After the request succeeds, the API will return the status and result of the video task. The following is an example response when the task is completed (each language corresponds to one `variant`):

```json theme={null}
{
  "id": "f57e99c4f60f4373a15517742ce2357d",
  "started_at": 1769262721.823,
  "finished_at": 1769264698.3,
  "elapsed": 1976.477,
  "status": "succeeded",
  "progress": {
    "percent": 100,
    "stage": "producing",
    "message": "rendering scene 2"
  },
  "request": {
    "prompt": "用 20 秒讲清楚什么是向量数据库，适合零基础观众，结尾给一句记忆点",
    "langs": [
      "zh-cn",
      "en"
    ],
    "aspect": "9:16",
    "duration": 20
  },
  "response": {
    "success": true,
    "data": {
      "variants": [
        {
          "lang": "zh-cn",
          "aspect": "9:16",
          "kind": "video",
          "title": "什么是向量数据库",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001"
        },
        {
          "lang": "en",
          "aspect": "9:16",
          "kind": "video",
          "title": "What is a vector database",
          "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002"
        }
      ],
      "project": {
        "tarball_url": null,
        "outputs": [
          "https://…/zh.mp4",
          "https://…/en.mp4"
        ]
      },
      "percent": 100,
      "stage": "producing",
      "progress": [
        {
          "stage": "producing",
          "message": "rendering scene 2",
          "pct": 60,
          "t": 1750000000
        }
      ]
    }
  }
}
```

The returned result fields are described as follows:

* `id`: The ID of this video task, used to uniquely identify this video generation task.
* `status`: The task status, with possible values of `pending → planning → producing → succeeded` (or `failed`). Whether the task has been completed is determined by this top-level `status`.
* `elapsed`: Time elapsed for the task (seconds).
* `progress`: The top-level progress object. `percent` (0–100) will be set to 100 upon task success; `stage` and `message` reflect the latest progress event from the AI director (therefore, after success, `stage` may still be the final execution stage such as `producing`) and can be directly used to display a progress bar.
* `request`: The request body when initiating the task.
* `response`: The task response information.
  * `success`: Whether the task succeeded.
  * `data.variants`: Each language corresponds to one completed video object, including `lang`, `aspect`, `title`, `output_url` (completed video download URL), and more.
  * `data.project`: The entire project output, including `tarball_url` (project package) and `outputs` (all completed video links).
  * `data.progress`: An array of progress events appended by stage (append-only log), which can be used to display detailed real-time progress.
* `created_at`: Task creation time, Unix timestamp (seconds).
* `started_at`: Task start execution time, Unix timestamp (seconds). It is null when the task has not started.
* `finished_at`: Task completion time, Unix timestamp (seconds). It is null when the task has not been completed.

## Query History List

Pass `action: retrieve_batch` to retrieve the most recent tasks of the currently logged-in executor (in reverse chronological order by creation time), which can be used for the "My Videos" list page. The history list is isolated by login identity.

**Request Body** includes:

| Field | Type | Required | Description |
| - | - | - | - |
| `action` | string | Yes | Fixed as `retrieve_batch` |
| `limit` | int | No | Number of results to return, default 20; valid range is 1–100 |
| `created_at_max` | int | No | Only return tasks strictly earlier than this Unix timestamp (excluding the boundary value, for pagination) |
| `created_at_min` | int | No | Only return tasks strictly later than this Unix timestamp (excluding the boundary value) |

### Code Example

The corresponding CURL code is as follows:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/maestro/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "retrieve_batch",
  "limit": 20
}'
```

### Response Example

After the request succeeds, the API will return the current user's historical task list:

```json theme={null}
{
  "count": 2,
  "items": [
    {
      "id": "f57e99c4f60f4373a15517742ce2357d",
      "started_at": 1769262721.823,
      "finished_at": 1769264698.3,
      "elapsed": 1976.477,
      "status": "succeeded",
      "progress": {
        "percent": 100,
        "stage": "producing",
        "message": "rendering scene 2"
      },
      "request": {
        "prompt": "…",
        "langs": [
          "zh-cn",
          "en"
        ],
        "aspect": "9:16",
        "duration": 20
      },
      "response": {
        "success": true,
        "data": {
          "variants": [
            {
              "lang": "zh-cn",
              "output_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003"
            }
          ]
        }
      }
    }
  ]
}
```

The returned result fields are described as follows:

* `count`: The total number of tasks visible to the currently logged-in executor, unaffected by time conditions or `limit`.
* `items`: An array of tasks filtered by time conditions and `limit`, sorted in descending order by creation time; the format of each element is consistent with the return result of "Query a Single Task".

## Polling Recommendations

Since video production takes a relatively long time, `status` will go through `pending → planning → producing → succeeded` (or `failed`). It is recommended to poll every 5–10 seconds until `status` changes to `succeeded` or `failed`. You can use the top-level `progress.percent` to display a real-time progress bar. **Polling this API is free and does not consume credits.**

## Error Handling

When calling the API, if an error occurs, the API will return the corresponding error code and message. For example:

* `401 invalid_token`: Unauthorized, invalid or missing authorization token.
* `404 not_found`: Task not found, the given task\_id does not exist.
* `429 too_many_requests`: Too many requests, you have exceeded the rate limit.
* `500 api_error`: Internal server error, something went wrong on the server.

### Error Response Example

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

## Conclusion

Through this document, you have learned how to use the Maestro task query API to query the status and result of a single task, as well as retrieve the current user's historical task list. We hope this document helps you better integrate and use this API. If you have any questions, please feel free to contact our technical support team.

## Related APIs

* [Maestro Video Generation API Integration Guide](/en/guides/maestro/maestro_videos): Automatically produce a subtitle-enabled finished video using a natural language prompt. After submission, `task_id` is returned, and then use this API to poll for results.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.