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-1.0-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,
  "page_size": 20,
  "page_token": "<string>",
  "sort_by": "created_at",
  "tags": [
    "<string>"
  ]
}
'

import requests

url = "https://api.worldlabs.ai/marble/v1/worlds:list"

payload = {
    "created_after": "2023-11-07T05:31:56Z",
    "created_before": "2023-11-07T05:31:56Z",
    "is_public": True,
    "page_size": 20,
    "page_token": "<string>",
    "sort_by": "created_at",
    "tags": ["<string>"]
}
headers = {
    "WLT-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'WLT-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    created_after: '2023-11-07T05:31:56Z',
    created_before: '2023-11-07T05:31:56Z',
    is_public: true,
    page_size: 20,
    page_token: '<string>',
    sort_by: 'created_at',
    tags: ['<string>']
  })
};

fetch('https://api.worldlabs.ai/marble/v1/worlds:list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.worldlabs.ai/marble/v1/worlds:list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'created_after' => '2023-11-07T05:31:56Z',
    'created_before' => '2023-11-07T05:31:56Z',
    'is_public' => true,
    'page_size' => 20,
    'page_token' => '<string>',
    'sort_by' => 'created_at',
    'tags' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "WLT-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.worldlabs.ai/marble/v1/worlds:list"

	payload := strings.NewReader("{\n  \"created_after\": \"2023-11-07T05:31:56Z\",\n  \"created_before\": \"2023-11-07T05:31:56Z\",\n  \"is_public\": true,\n  \"page_size\": 20,\n  \"page_token\": \"<string>\",\n  \"sort_by\": \"created_at\",\n  \"tags\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("WLT-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.worldlabs.ai/marble/v1/worlds:list")
  .header("WLT-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"created_after\": \"2023-11-07T05:31:56Z\",\n  \"created_before\": \"2023-11-07T05:31:56Z\",\n  \"is_public\": true,\n  \"page_size\": 20,\n  \"page_token\": \"<string>\",\n  \"sort_by\": \"created_at\",\n  \"tags\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.worldlabs.ai/marble/v1/worlds:list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["WLT-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"created_after\": \"2023-11-07T05:31:56Z\",\n  \"created_before\": \"2023-11-07T05:31:56Z\",\n  \"is_public\": true,\n  \"page_size\": 20,\n  \"page_token\": \"<string>\",\n  \"sort_by\": \"created_at\",\n  \"tags\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "worlds": [
    {
      "display_name": "<string>",
      "world_id": "<string>",
      "world_marble_url": "<string>",
      "assets": {
        "caption": "<string>",
        "imagery": {
          "pano_url": "<string>"
        },
        "mesh": {
          "collider_mesh_url": "<string>",
          "full_res_mesh_url": "<string>",
          "hq_mesh_url": "<string>"
        },
        "splats": {
          "semantics_metadata": {
            "ground_plane_offset": 123,
            "metric_scale_factor": 123
          },
          "spz_urls": {}
        },
        "thumbnail_url": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "model": "<string>",
      "permission": {
        "allow_id_access": false,
        "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>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<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 visibility. true=public only, false=private only, null=all

model

Filter by model used for generation. Legacy names are deprecated; use the new lowercase names.

Available options:

marble-1.0-draft,

marble-1.0,

marble-1.1,

marble-1.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). Use cursor from next_page_token in previous response for consistent pagination.

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

Export a worldExport a generated world asset. PLY splat exports are converted synchronously, cached in GCS, and returned as completed operations. HQ mesh exports reuse the existing async mesh export service and return an in-progress operation.

⌘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,
  "page_size": 20,
  "page_token": "<string>",
  "sort_by": "created_at",
  "tags": [
    "<string>"
  ]
}
'

import requests

url = "https://api.worldlabs.ai/marble/v1/worlds:list"

payload = {
    "created_after": "2023-11-07T05:31:56Z",
    "created_before": "2023-11-07T05:31:56Z",
    "is_public": True,
    "page_size": 20,
    "page_token": "<string>",
    "sort_by": "created_at",
    "tags": ["<string>"]
}
headers = {
    "WLT-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'WLT-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    created_after: '2023-11-07T05:31:56Z',
    created_before: '2023-11-07T05:31:56Z',
    is_public: true,
    page_size: 20,
    page_token: '<string>',
    sort_by: 'created_at',
    tags: ['<string>']
  })
};

fetch('https://api.worldlabs.ai/marble/v1/worlds:list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.worldlabs.ai/marble/v1/worlds:list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'created_after' => '2023-11-07T05:31:56Z',
    'created_before' => '2023-11-07T05:31:56Z',
    'is_public' => true,
    'page_size' => 20,
    'page_token' => '<string>',
    'sort_by' => 'created_at',
    'tags' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "WLT-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.worldlabs.ai/marble/v1/worlds:list"

	payload := strings.NewReader("{\n  \"created_after\": \"2023-11-07T05:31:56Z\",\n  \"created_before\": \"2023-11-07T05:31:56Z\",\n  \"is_public\": true,\n  \"page_size\": 20,\n  \"page_token\": \"<string>\",\n  \"sort_by\": \"created_at\",\n  \"tags\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("WLT-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.worldlabs.ai/marble/v1/worlds:list")
  .header("WLT-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"created_after\": \"2023-11-07T05:31:56Z\",\n  \"created_before\": \"2023-11-07T05:31:56Z\",\n  \"is_public\": true,\n  \"page_size\": 20,\n  \"page_token\": \"<string>\",\n  \"sort_by\": \"created_at\",\n  \"tags\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.worldlabs.ai/marble/v1/worlds:list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["WLT-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"created_after\": \"2023-11-07T05:31:56Z\",\n  \"created_before\": \"2023-11-07T05:31:56Z\",\n  \"is_public\": true,\n  \"page_size\": 20,\n  \"page_token\": \"<string>\",\n  \"sort_by\": \"created_at\",\n  \"tags\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "worlds": [
    {
      "display_name": "<string>",
      "world_id": "<string>",
      "world_marble_url": "<string>",
      "assets": {
        "caption": "<string>",
        "imagery": {
          "pano_url": "<string>"
        },
        "mesh": {
          "collider_mesh_url": "<string>",
          "full_res_mesh_url": "<string>",
          "hq_mesh_url": "<string>"
        },
        "splats": {
          "semantics_metadata": {
            "ground_plane_offset": 123,
            "metric_scale_factor": 123
          },
          "spz_urls": {}
        },
        "thumbnail_url": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "model": "<string>",
      "permission": {
        "allow_id_access": false,
        "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>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Get started

Examples

Reference

Support & billing

List worlds

Authorizations

Body

Response