TokenLab

Worlds

Get World Status

Retrieves the status and result of a World Labs Marble world generation task

GET
/v1/worlds/generations/{id}

GET /v1/worlds/generations/{id} is a compatibility endpoint. It remains supported for existing integrations. New integrations poll GET /v1/tasks/{id} with the same task id; see Get Task Status.

This endpoint returns the status of a World Labs Marble generation task. Use the task id from the create response.

An expired or unavailable public task can return 404 async_task_not_found. If task ownership cannot be established for the current API key, the response is 403 task_not_owned.

Path Parameters

idstringpathrequired

World generation task ID.

Response

Only id and status are required in a successful status response. Task aliases, operation IDs, world assets, and captions are returned when available. A completed task does not guarantee that every asset URL is present. A failed task still returns HTTP 200: read status, error, and error_details.

world_marble_url opens the interactive World Labs viewer. Result files such as glb_url, pano_url, and thumbnail_url are TokenLab links; they are empty or absent until the task completes.

idstring

Public task ID.

task_idstring

Async task identifier alias.

operation_idstring

World Labs operation ID.

statusstring

Task status: pending, processing, completed, failed, or timeout.

world_idstring

World Labs world ID when completed.

world_marble_urlstring

URL for the generated Marble world when completed.

model_urlstring

Alias for the primary generated world/model URL.

glb_urlstring

Collider mesh GLB URL when available. A TokenLab media-result link that stays valid for 30 days.

pano_urlstring

Panorama image URL when available. A TokenLab media-result link that stays valid for 30 days.

thumbnail_urlstring

Thumbnail image URL when available. A TokenLab media-result link that stays valid for 30 days.

captionstring

Caption for the generated world.

errorstring | object

Error message when the task failed.

error_detailsobject

Failure details when the task failed: status, message, type, code, retryable, and param when a request field is at fault.

media_retentionobject

Saving status of the TokenLab media-result links in a completed response: days and items[] with url, kind, status, and expires_at. It can be absent; the links still work. See Data retention.

Request

curl --fail-with-body "https://api.tokenlab.sh/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" \
  -H "Authorization: Bearer sk-your-api-key"
{  "id": "string",  "task_id": "string",  "operation_id": "string",  "status": "pending",  "world_id": "string",  "world_marble_url": "string",  "model_url": "string",  "glb_url": "string",  "pano_url": "string",  "thumbnail_url": "string",  "caption": "string",  "error": "string",  "error_details": {    "projection_version": 0,    "status": 400,    "message": "string",    "type": "string",    "code": "string",    "param": "string",    "retryable": true,    "upstream": {      "source": "string",      "code": "string",      "message": "string",      "param": "string"    }  },  "media_retention": {    "days": 0,    "items": [      {        "url": "http://example.com",        "kind": "image",        "content_type": "string",        "status": "saving",        "expires_at": "2019-08-24T14:15:22Z"      }    ]  }}

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Path Parameters

id*string

World generation task ID.

Response

application/json

application/json

application/json