Skip to main content
GET
https://api.worldlens.co
/
api
/
v1
/
simulations
/
{simulation_id}
/
status
Simulation Status
curl --request GET \
  --url https://api.worldlens.co/api/v1/simulations/{simulation_id}/status/
{
  "200": {},
  "404": {},
  "500": {},
  "simulation_id": "<string>",
  "status": "<string>",
  "result_url": "<string>",
  "created_at": "<string>",
  "build_started_at": "<string>",
  "build_completed_at": "<string>",
  "prompt": "<string>",
  "error": {
    "error.message": "<string>",
    "error.code": "<string>",
    "error.details": {}
  }
}

​
Overview

The Simulation Status API allows you to monitor the progress of your simulation generation. Use this endpoint to check whether your simulation is queued, processing, completed, or has encountered an error.

​
Authentication

curl -X GET "https://api.worldlens.co/api/v1/simulations/{simulation_id}/status/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
This endpoint supports anonymous access, allowing you to check status without authentication if you have the simulation ID.

​
Path Parameters

​
simulation_id
string
required
The unique identifier of the simulation returned when you created it

​
Example Request

curl -X GET "https://api.worldlens.co/api/v1/simulations/sim_abc123def456/status/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

​
Response

​
simulation_id
string
The unique identifier of the simulation (“id”)
​
status
string
Current status of the simulation
  • queued: Waiting to be processed
  • processing: Currently being generated
  • completed: Successfully completed
  • failed: Generation failed
​
result_url
string
Absolute URL to the final simulation (null unless status == complete)
​
created_at
string
ISO 8601 timestamp when the simulation was created
​
build_started_at
string
ISO 8601 timestamp when processing began (null if not started)
​
build_completed_at
string
ISO 8601 timestamp when processing completed (null if not completed)
​
prompt
string
The original prompt used to generate the simulation
​
error
object
Error details if status is failed

​
Example Responses

​
Queued Simulation

{
  "simulation_id": "sim_abc123def456",
  "status": "queued",
  "result_url": null,
  "created_at": "2024-01-15T10:30:00Z",
  "build_started_at": null,
  "build_completed_at": null,
  "prompt": null
}

​
Processing Simulation

{
  "simulation_id": "sim_abc123def456",
  "status": "processing",
  "result_url": null,
  "created_at": "2024-01-15T10:30:00Z",
  "build_started_at": "2024-01-15T10:31:15Z",
  "build_completed_at": null,
  "prompt": null
}

​
Completed Simulation

{
  "simulation_id": "sim_abc123def456",
  "status": "completed",
  "result_url": "/api/v1/simulations/sim_abc123def456/",
  "created_at": "2024-01-15T10:30:00Z",
  "build_started_at": "2024-01-15T10:31:15Z",
  "build_completed_at": "2024-01-15T10:35:42Z",
  "prompt": null
}

​
Failed Simulation

{
  "simulation_id": "sim_abc123def456",
  "status": "failed",
  "result_url": null,
  "created_at": "2024-01-15T10:30:00Z",
  "build_started_at": "2024-01-15T10:31:15Z",
  "build_completed_at": null,
  "prompt": null,
  "error": {
    "message": "Unable to generate terrain from the provided prompt",
    "code": "TERRAIN_GENERATION_FAILED",
    "details": {
      "stage": "creating_terrain",
      "reason": "Insufficient geographic context in prompt"
    }
  }
}

​
Processing Stages

Simulations go through several stages during generation:
StageDescription
parsing_promptAnalyzing and understanding the input prompt
creating_terrainGenerating the base terrain and environment
placing_buildingsAdding structures and buildings
generating_agentsCreating and positioning actors
configuring_behaviorsSetting up agent behaviors and interactions
finalizing_simulationFinal optimization and validation

​
Status Codes

​
200
OK
Status retrieved successfully
​
404
Not Found
Simulation not found
​
500
Internal Server Error
Server error retrieving status

​
Polling Best Practices

When polling for status updates:
  1. Start with short intervals: Poll every 5-10 seconds initially
  2. Increase intervals gradually: Move to 30-60 seconds for longer simulations
  3. Respect rate limits: Don’t exceed your API rate limits
  4. Use webhooks when possible: Consider using webhook notifications instead of polling

​
Next Steps