Task Status

Since 3D generation is a computationally intensive process, the Triverse API operates asynchronously. When you create a task, the API returns a task_uuid immediately. You must then check the status of this task to know when it is finished.

Query Task Status

Retrieves the current state, progress, and output of a specific task.

Endpoint

GET /tasks/{task_uuid}

Authentication

Required (Bearer Token)

Path Parameters

Parameter	Type	Description
`task_uuid`	UUID	The unique identifier of the task.

Example Request

cURL

curl -X 'GET' \
  'https://api.triverse.ai/api/v1/tasks/92483a80-236c-4889-9a95-4c90bb64dfd8' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'

JavaScript

const response = await fetch(
  "https://api.triverse.ai/api/v1/tasks/92483a80-236c-4889-9a95-4c90bb64dfd8",
  {
    method: "GET",
    headers: {
      Accept: "application/json",
      Authorization: "Bearer <YOUR_API_KEY>",
    },
  },
);
const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
    "https://api.triverse.ai/api/v1/tasks/92483a80-236c-4889-9a95-4c90bb64dfd8",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer <YOUR_API_KEY>",
    },
)
print(response.json())

Response Structure

Field	Type	Description
`task_uuid`	UUID	Task UUID.
`flow_name`	String	Generation flow type.
`status`	String	Public task status: `PENDING`, `QUEUED`, `RUNNING`, `SUCCESS`, `FAILED`, or `CANCELLED`.
`progress`	Integer	Estimated progress percentage, 0 to 100.
`created_at`	String	Task creation time in UTC.
`started_at`	String / Null	Optional UTC time when execution first started.
`completed_at`	String / Null	Optional UTC time when the task reached a terminal status.
`input`	Object / Null	Public allowlisted input fields. This is intended for retry, regenerate, and client reconciliation.
`output`	Object / Null	Public allowlisted result fields, including generated asset URLs when available.
`error`	Object / Null	Public error object for failed tasks, with `code`, `message`, and optional `suggestion`.
`queue`	Object / Null	Optional public queue summary with `is_queued`, `position`, and `estimated_wait_seconds`.

The status response does not expose internal scheduler, worker, pricing manifest, analytics, or tracking fields. Fields such as flowRunId, rawPrefectState, statusDetail, userId, workQueueName, deploymentId, pricingSnapshot, and analytics context are not part of the public API.

For textured model flows such as image-to-model, multiview-to-model, text-to-model, text-to-texture, and texture-model, the output object exposes public model and preview URLs such as geometry_model_url, textured_model_url, and preview_url.

Example Response

{
  "code": 0,
  "message": "success",
  "data": {
    "task_uuid": "92483a80-236c-4889-9a95-4c90bb64dfd8",
    "flow_name": "image-to-model",
    "status": "SUCCESS",
    "progress": 100,
    "created_at": "2026-05-27T00:00:00Z",
    "started_at": "2026-05-27T00:00:12Z",
    "completed_at": "2026-05-27T00:08:44Z",
    "input": {
      "image_url": "https://.../input.png",
      "model_version": "v2",
      "polygon_limit": 1000000,
      "texture_size": 1024
    },
    "output": {
      "geometry_model_url": ["https://.../geometry.glb"],
      "textured_model_url": ["https://.../textured.glb"],
      "preview_url": "https://.../preview.png"
    },
    "error": null,
    "queue": null
  }
}

Task Lifecycle

PENDING: The task has been accepted and created, but detailed queue state is not available yet.
QUEUED: The task is waiting before execution.
RUNNING: A worker has picked up the task and is currently processing it.
SUCCESS: The task completed successfully. Assets are now available for download.
FAILED: An error occurred during processing. Check the error message for details.
CANCELLED: The task was manually cancelled by the user or system.

Polling vs. WebSockets

While you can poll this endpoint every few seconds to check for updates, we highly recommend using WebSockets for real-time notifications. WebSockets are more efficient and provide a better experience for your users.

On this page