Worlds

List Worlds

List worlds with optional filters.

Returns worlds created through the API with optional filtering and pagination.

Args: request: List request with optional filters:

page_size: Number of results per page (default: 10)
page_token: Pagination token from previous response
status: Filter by status (e.g., “COMPLETED”)
model: Filter by model name (e.g., “Marble 0.1-plus”)
tags: Filter by tags (matches worlds with any tag)
is_public: Filter by visibility (true=public, false=private, null=all)
created_after: Filter by creation time (after timestamp)
created_before: Filter by creation time (before timestamp)
sort_by: Sort order (“created_at” or “updated_at”)

Returns: ListWorldsResponse with worlds list and next_page_token for pagination.

Raises: HTTPException: 400 if invalid parameters HTTPException: 500 if request fails

POST

marble

worlds:list

List Worlds

curl --request POST \
  --url https://api.worldlabs.ai/marble/v1/worlds:list \
  --header 'Content-Type: application/json' \
  --header 'WLT-Api-Key: <api-key>' \
  --data '
{
  "created_after": "2023-11-07T05:31:56Z",
  "created_before": "2023-11-07T05:31:56Z",
  "is_public": true,
  "model": "Marble 0.1-mini",
  "page_size": 20,
  "page_token": "<string>",
  "sort_by": "created_at",
  "status": "SUCCEEDED",
  "tags": [
    "<string>"
  ]
}
'

{
  "worlds": [
    {
      "display_name": "<string>",
      "world_id": "<string>",
      "world_marble_url": "<string>",
      "assets": {
        "caption": "<string>",
        "imagery": {
          "pano_url": "<string>"
        },
        "mesh": {
          "collider_mesh_url": "<string>"
        },
        "splats": {
          "spz_urls": {}
        },
        "thumbnail_url": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "model": "<string>",
      "permission": {
        "allowed_readers": [
          "<string>"
        ],
        "allowed_writers": [
          "<string>"
        ],
        "public": false
      },
      "tags": [
        "<string>"
      ],
      "updated_at": "2023-11-07T05:31:56Z",
      "world_prompt": {
        "text_prompt": "<string>",
        "type": "text"
      }
    }
  ],
  "next_page_token": "<string>"
}

Authorizations

WLT-Api-Key

string

header

required

API key for authentication. Get your key from the developer portal.

Body

application/json

Request to list API-generated worlds with optional filters.

created_after

string<date-time> | null

Filter worlds created after this timestamp (inclusive)

created_before

string<date-time> | null

Filter worlds created before this timestamp (exclusive)

is_public

boolean | null

Filter by public visibility (true=public, false=private)

model

enum<string> | null

Filter by model used for generation

Available options:

Marble 0.1-mini,

Marble 0.1-plus

page_size

integer

default:20

Number of results per page (1-100)

Required range: 1 <= x <= 100

page_token

string | null

Cursor token for pagination (opaque base64 string from previous response)

sort_by

enum<string>

default:created_at

Sort results by created_at or updated_at

Available options:

created_at,

updated_at

status

enum<string> | null

Filter by world status

Available options:

SUCCEEDED,

PENDING,

FAILED,

RUNNING

Response

Successful Response

Response containing a list of API-generated worlds.

worlds

World · object[]

required

List of worlds

Show child attributes

next_page_token

string | null

Token for fetching the next page of results

Get an OperationGet an operation by ID. Poll this endpoint to check the status of a long-running operation. When done=true, the response field contains the generated world. Args: operation_id: The operation identifier from /worlds:generate. Returns: GetOperationResponse[World] with: - operation_id: Operation identifier - created_at: Creation timestamp - updated_at: Last update timestamp - expires_at: Expiration timestamp - done: true when complete, false while in progress - error: Error details if failed, null otherwise - metadata: Progress information and world_id - response: Generated World if done=true, null otherwise Raises: HTTPException: 401 if unauthorized HTTPException: 404 if operation not found HTTPException: 500 if request fails

⌘I

List Worlds

curl --request POST \
  --url https://api.worldlabs.ai/marble/v1/worlds:list \
  --header 'Content-Type: application/json' \
  --header 'WLT-Api-Key: <api-key>' \
  --data '
{
  "created_after": "2023-11-07T05:31:56Z",
  "created_before": "2023-11-07T05:31:56Z",
  "is_public": true,
  "model": "Marble 0.1-mini",
  "page_size": 20,
  "page_token": "<string>",
  "sort_by": "created_at",
  "status": "SUCCEEDED",
  "tags": [
    "<string>"
  ]
}
'

{
  "worlds": [
    {
      "display_name": "<string>",
      "world_id": "<string>",
      "world_marble_url": "<string>",
      "assets": {
        "caption": "<string>",
        "imagery": {
          "pano_url": "<string>"
        },
        "mesh": {
          "collider_mesh_url": "<string>"
        },
        "splats": {
          "spz_urls": {}
        },
        "thumbnail_url": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "model": "<string>",
      "permission": {
        "allowed_readers": [
          "<string>"
        ],
        "allowed_writers": [
          "<string>"
        ],
        "public": false
      },
      "tags": [
        "<string>"
      ],
      "updated_at": "2023-11-07T05:31:56Z",
      "world_prompt": {
        "text_prompt": "<string>",
        "type": "text"
      }
    }
  ],
  "next_page_token": "<string>"
}

Get started

Reference

Support & billing

List Worlds

Authorizations

Body

Response