> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# List Worlds

> Lists completed World Labs Marble worlds created through TokenLab

List completed World Labs Marble worlds created through TokenLab. Results are scoped to your organization and only include resources created through TokenLab.

Use `/v1/worlds/generations/{id}` for pending or failed generation tasks. This list returns completed worlds that TokenLab has indexed after generation.

## Request Body

<ParamField body="page_size" type="integer" default="20">
  Number of worlds to return, from 1 to 100.
</ParamField>

<ParamField body="page_token" type="string">
  Pagination token from the previous response.
</ParamField>

<ParamField body="status" type="string">
  Optional status filter. TokenLab returns completed worlds for `SUCCEEDED`; other statuses belong to the generation task endpoint.
</ParamField>

<ParamField body="model" type="string">
  Optional Marble model filter.
</ParamField>

<ParamField body="tags" type="array">
  Optional tag filter.
</ParamField>

<ParamField body="is_public" type="boolean">
  Optional visibility filter.
</ParamField>

<ParamField body="created_after" type="string">
  Only return worlds created after this timestamp.
</ParamField>

<ParamField body="created_before" type="string">
  Only return worlds created before this timestamp.
</ParamField>

<ParamField body="sort_by" type="string" default="created_at">
  Sort by `created_at` or `updated_at`.
</ParamField>

<ParamField body="sort_order" type="string" default="desc">
  Sort direction: `asc` or `desc`.
</ParamField>

## Response

<ResponseField name="worlds" type="array">
  Array of world records.
</ResponseField>

<ResponseField name="next_page_token" type="string">
  Token for the next page, or `null`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/worlds/list" \
    -H "Authorization: Bearer sk-your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"page_size": 20, "status": "SUCCEEDED", "model": "marble-1.1"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.tokenlab.sh/v1/worlds/list",
      headers={"Authorization": "Bearer sk-your-api-key"},
      json={"page_size": 20, "status": "SUCCEEDED", "model": "marble-1.1"},
  )
  print(response.json()["worlds"])
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.tokenlab.sh/v1/worlds/list', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk-your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ page_size: 20, status: 'SUCCEEDED', model: 'marble-1.1' })
  });
  console.log((await response.json()).worlds);
  ```
</RequestExample>