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

# Simulation Status

> Check the current status and progress of a simulation

## 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

<CodeGroup>
  ```bash API Key theme={null}
  curl -X GET "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/" \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```bash Token theme={null}
  curl -X GET "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/" \
    -H "Authorization: Token YOUR_AUTH_TOKEN"
  ```

  ```bash Anonymous theme={null}
  curl -X GET "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/"
  ```
</CodeGroup>

<Note>
  This endpoint supports anonymous access, allowing you to check status without authentication if you have the simulation ID.
</Note>

## Path Parameters

<ParamField path="simulation_id" type="string" required>
  The unique identifier of the simulation returned when you created it
</ParamField>

## Example Request

```bash theme={null}
curl -X GET "https://api.vects.ai/api/v1/simulations/sim_abc123def456/status/" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

## Response

<ResponseField name="simulation_id" type="string">
  The unique identifier of the simulation ("id")
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the simulation

  * `queued`: Waiting to be processed
  * `processing`: Currently being generated
  * `completed`: Successfully completed
  * `failed`: Generation failed
</ResponseField>

<ResponseField name="result_url" type="string">
  Absolute URL to the final simulation (null unless `status == complete`)
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the simulation was created
</ResponseField>

<ResponseField name="build_started_at" type="string">
  ISO 8601 timestamp when processing began (null if not started)
</ResponseField>

<ResponseField name="build_completed_at" type="string">
  ISO 8601 timestamp when processing completed (null if not completed)
</ResponseField>

<ResponseField name="prompt" type="string">
  The original prompt used to generate the simulation
</ResponseField>

<ResponseField name="error" type="object">
  Error details if status is `failed`

  <Expandable title="error properties">
    <ResponseField name="error.message" type="string">
      Human-readable error description
    </ResponseField>

    <ResponseField name="error.code" type="string">
      Machine-readable error code
    </ResponseField>

    <ResponseField name="error.details" type="object">
      Additional error context
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Responses

### Queued Simulation

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

| Stage                   | Description                                  |
| ----------------------- | -------------------------------------------- |
| `parsing_prompt`        | Analyzing and understanding the input prompt |
| `creating_terrain`      | Generating the base terrain and environment  |
| `placing_buildings`     | Adding structures and buildings              |
| `generating_agents`     | Creating and positioning actors              |
| `configuring_behaviors` | Setting up agent behaviors and interactions  |
| `finalizing_simulation` | Final optimization and validation            |

## Status Codes

<ResponseField name="200" type="OK">
  Status retrieved successfully
</ResponseField>

<ResponseField name="404" type="Not Found">
  Simulation not found
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error retrieving status
</ResponseField>

## 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

* Once status is `completed`, retrieve results with the [Results API](/api-reference/simulation/results)
* Learn about [Risk Analysis](/api-reference/simulation/risk-analysis) for safety assessments
* Explore [Urban Mobility MARL](/api-reference/marl/websocket-overview) for real-time simulations