--- title: "Get Operation" method: GET path: "/marble/v1/operations/{operation_id}" --- # Get Operation `GET /marble/v1/operations/{operation_id}` ## Request - Base URL: `https://api.worldlabs.ai` - URL: `https://api.worldlabs.ai/marble/v1/operations/{operation_id}` - Auth: API key in header `WLT-Api-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Get 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 - cost: Settled credit cost breakdown; populated only when the operation completed successfully (done=true with no error) and a public price is known for its operation type. Failed or in-progress operations return null. Raises: HTTPException: 401 if unauthorized HTTPException: 404 if operation not found HTTPException: 500 if request fails ## Path parameters - `operation_id` string, required ## Response `200` Successful Response - GetOperationResponseUnionWorldPanoDepthToRgbResultExportWorldResult - `cost` OperationCost: Settled credit cost for a successful operation. - `line_items` OperationCostLineItem[]: Usage events that make up the operation's total credits - `credits` integer, required: Credits charged for this usage event - `name` string, required: Human-readable usage event name - `total_credits` integer, required: Total credits charged for the operation - `created_at` string, date-time, nullable: Creation timestamp - `done` boolean, required: True if the operation is completed - `error` OperationError: Error information for a failed operation. - `code` integer, nullable: Error code - `message` string, nullable: Error message - `expires_at` string, date-time, nullable: Expiration timestamp - `metadata` object, nullable: Service-specific metadata, such as progress percentage - `operation_id` string, required: Operation identifier - `response` union: Result payload when done=true and no error. Structure depends on operation type. - World: A generated world, including asset URLs. - `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' - PanoDepthToRgbResult: Result from depth-to-RGB panorama generation. Returned inside ``Operation.response`` when the operation completes successfully (``done=true``). - `pano_url` string, nullable: URL of the generated RGB panorama image. Available when the operation succeeds. - ExportWorldResult: Downloadable exported world asset. - `asset_type` 'splats' | 'mesh', required: Exported asset family - `format` 'ply' | 'glb', required: Exported file format - `mesh_variant` 'textured' | 'vertex_colored', nullable: Mesh variant returned for this export, if applicable - `resolution` string, nullable: Splat resolution used for this export, if applicable - `url` string, required: Download URL for the exported asset - `updated_at` string, date-time, nullable: Last update timestamp ## Other responses - `422`: Validation Error ## Changes - **2026-11-03** `4a3ed614672e`: 1 info - added `depth-pano, image, inpaint-pano, multi-image, text, video` discriminator mapping keys to the `response/anyOf[subschema #1: World]/world_prompt/anyOf[subschema #1]/` response property for the response status `200` [Operation history](https://skmtc.dev/worldlabs/apis/marble-public-api-v1/changes/marble/v1/operations/:operation_id/get.md) --- [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/4a3ed614672e?raw)