--- title: "List Worlds" method: POST path: "/marble/v1/worlds:list" --- # List Worlds `POST /marble/v1/worlds:list` 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 ## Request body - ListWorldsRequest — Request to list API-generated worlds with optional filters. - `created_after` string, date-time, nullable — Filter worlds created after this timestamp (inclusive) - `created_before` string, date-time, nullable — Filter worlds created before this timestamp (exclusive) - `is_public` boolean, nullable — Filter by visibility. true=public only, false=private only, null=all - `model` union — Filter by model used for generation. Legacy names are deprecated; use the new lowercase names. - 'marble-1.0-draft' | 'marble-1.0' | 'marble-1.1' | 'marble-1.1-plus' - 'Marble 0.1-mini' | 'Marble 0.1-plus' | 'Marble 1.1-plus' - `page_size` integer — Number of results per page (1-100) - `page_token` string, nullable — Cursor token for pagination (opaque base64 string from previous response). Use cursor from next_page_token in previous response for consistent pagination. - `sort_by` 'created_at' | 'updated_at' — Sort results by created_at or updated_at - `status` 'SUCCEEDED' | 'PENDING' | 'FAILED' | 'RUNNING', nullable — Filter by world status - `tags` string[], nullable — Filter by tags (returns worlds with ANY of these tags) ## Response `200` Successful Response - ListWorldsResponse — Response containing a list of API-generated worlds. - `next_page_token` string, nullable — Token for fetching the next page of results - `worlds` World[], required — List of worlds - `assets` WorldAssets — Downloadable outputs of world generation. - `caption` string, nullable — AI-generated description of the world - `imagery` ImageryAssets — Imagery asset URLs. - `pano_url` string, nullable — Panorama image URL - `mesh` MeshAssets — Mesh asset URLs. - `collider_mesh_url` string, nullable — Collider mesh URL - `full_res_mesh_url` string, nullable — Full-resolution vertex-colored mesh URL - `hq_mesh_url` string, nullable — High-quality textured mesh URL - `splats` SplatAssets — Gaussian splat asset URLs. - `semantics_metadata` WorldSemanticsMetadata — Semantic metadata describing how to interpret the generated splat asset in real-world units. The exported asset is in arbitrary model units. Apply the transform below to convert to a metric, ground-aligned frame: metric_xyz = raw_xyz * metric_scale_factor aligned_xyz = metric_xyz - (0, ground_plane_offset, 0) Both fields are populated on every world generated by the current pipeline. They remain Optional only for backwards compatibility with worlds generated before December 2025, which predate metric-scale estimation. TODO: once pre-December-2025 worlds are migrated or aged out, tighten these fields to non-Optional and drop the `| None` from the type. - `ground_plane_offset` number, nullable — Vertical (Y-axis) offset, in meters, of the detected ground plane in the metric-scaled frame. Subtract from Y after applying `metric_scale_factor` to place the ground at y=0. - `metric_scale_factor` number, nullable — Multiplicative factor that converts raw asset coordinates to meters. Multiply all XYZ positions (and isotropic scales) by this value. A value of 1.0 means scale could not be inferred and the asset was left in model units. - `spz_urls` object, nullable — URLs for SPZ format Gaussian splat files - `thumbnail_url` string, nullable — Thumbnail URL for the world - `created_at` string, date-time, nullable — Creation timestamp - `display_name` string, required — Display name - `model` string, nullable — Model used for generation - `permission` Permission — Access control permissions for a resource. - `allow_id_access` boolean - `allowed_readers` string[] - `allowed_writers` string[] - `public` boolean - `tags` string[], nullable — Tags associated with the world - `updated_at` string, date-time, nullable — Last update timestamp - `world_id` string, required — World identifier - `world_marble_url` string, required — World Marble URL - `world_prompt` union — World prompt - WorldTextPromptOutput — Input prompt class for text-conditioned world generation. - `text_prompt` string, nullable - `type` 'text' - Prompt — For world models generating a world from a single image (+ text). Images can be generated using the :image-generation method. If no text prompt is provided, it will be generated via recaption. - `image_prompt` Content, required — Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB). - `data_base64` string, nullable - `extension` string, nullable — File extension without dot - `uri` string, nullable - `is_pano` boolean - `text_prompt` string, nullable - `type` 'image' - MultiImagePromptOutput — For world models supporting multi-image (+ text) input. - `multi_image_prompt` SphericallyLocatedContentOutput[], required - `azimuth` number, nullable - `data_base64` string, nullable - `extension` string, nullable — File extension without dot - `uri` string, nullable - `reconstruct_images` boolean - `text_prompt` string, nullable - `type` 'multi-image' - VideoPromptOutput — For world models supporting video (+ text) input. - `text_prompt` string, nullable - `type` 'video' - `video_prompt` Content, required — Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB). - `data_base64` string, nullable - `extension` string, nullable — File extension without dot - `uri` string, nullable - DepthPanoPrompt — For models conditioned on a depth pano and text. When depth_pano_image is a log-encoded PNG, z_min and z_max are required to decode it correctly. When it is an EXR file containing raw float depth values, z_min and z_max will both be ignored. Please set z_min and z_max both to None when using an EXR file. - `depth_pano_image` Content, required — Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB). - `data_base64` string, nullable - `extension` string, nullable — File extension without dot - `uri` string, nullable - `text_prompt` string, nullable - `type` 'depth-pano' - `z_max` number, nullable - `z_min` number, nullable - InpaintPanoPrompt — For models that inpaint the masked portion of a pano image. - `pano_image` Content, required — Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB). - `data_base64` string, nullable - `extension` string, nullable — File extension without dot - `uri` string, nullable - `pano_mask` Content, required — Represents content (media, text, images) that can be stored inline or via URL. Supports both direct data storage (up to 10MB) and URL references (up to 20MB). - `data_base64` string, nullable - `extension` string, nullable — File extension without dot - `uri` string, nullable - `text_prompt` string, nullable - `type` 'inpaint-pano' ## Other responses - `422` — Validation Error --- [API](https://skmtc.dev/worldlabs/apis/marble-public-api-v1.md) · [All operations](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/revisions/731ef579549c?raw)