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

# List Worlds

> Lists completed World Labs Marble worlds created through AI Sonar

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

Use `/v1/worlds/generations/{id}` for pending or failed generation tasks. This list returns completed worlds that AI Sonar 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. AI Sonar 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.aisonar.dev/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.aisonar.dev/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.aisonar.dev/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>