Query task status¶

Read the status summary of the export task.

GET https://api.moi.matrixorigin.cn/v5/export/task/$TASK_ID/state

Preparation before calling¶

First Query task details to confirm the export task whose status you want to view. Prepare a personal access token with access to the target workspace, the target workspace ID, and the export task ID.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$TASK_ID: To view the status of the exported task ID, fill in the task ID position in the request address.

Request example¶

curl "https://api.moi.matrixorigin.cn/v5/export/task/$TASK_ID/state" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Path parameters¶

Parameters	Type	Is it required	Description
`task_id`	string	Yes	The export task ID whose status is to be queried.

Successful response¶

Returns 200 on success. data only provides an aggregate count of file processing status; pending, running and failed must be checked, HTTP success cannot be considered export completion.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 4,
    "pending": 0,
    "running": 1,
    "failed": 1,
    "completed": 2
  }
}

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.total`	integer	The total number of files in the task.
`data.pending`	integer	Number of files to be processed.
`data.running`	integer	The number of files being exported.
`data.failed`	integer	The number of files that failed to export.
`data.completed`	integer	Number of files that have been successfully completed.

Error response¶

A failed query can return HTTP 200 with code: "ErrServer" and data: null. Check both the HTTP status and the response code. Read the status counts only when code is OK.

The following is a generic error response. A missing task can also produce this response, but neither ErrServer nor the message identifies the cause. Verify the workspace and task ID, then use the export task list to find a readable task before querying its status again. If the confirmed task still fails, record the HTTP status, response code, and request time and contact support.

{
  "code": "ErrServer",
  "msg": "Internal server error",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`200`	`ErrServer`	The task does not exist or the status statistics reading fails.	Verify the workspace and task ID in the export task list before retrying. The generic error alone cannot confirm a missing task.
`403`	`ErrForbidden`	The current identity does not have permission to read the task.	Request that read permission be granted to the export task.

Follow-up operations¶

When there are still files waiting or being processed, continue to query this interface with the same task ID. The export is complete when both the waiting and processing quantities are 0 and there are no failures. When there is a failure, Query export files locates the failed item, and if necessary, Rerun task.

Last updated on Oct 19, 2026