Simulation Status
curl --request GET \
--url https://api.vects.ai/api/v1/simulations/{simulation_id}/status/import requests
url = "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.vects.ai/api/v1/simulations/{simulation_id}/status/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.vects.ai/api/v1/simulations/{simulation_id}/status/")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vects.ai/api/v1/simulations/{simulation_id}/status/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"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": {}
}
}Simulation APIs
Simulation Status
Check the current status and progress of a simulation
GET
/
api
/
v1
/
simulations
/
{simulation_id}
/
status
/
Simulation Status
curl --request GET \
--url https://api.vects.ai/api/v1/simulations/{simulation_id}/status/import requests
url = "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.vects.ai/api/v1/simulations/{simulation_id}/status/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.vects.ai/api/v1/simulations/{simulation_id}/status/")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vects.ai/api/v1/simulations/{simulation_id}/status/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"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.vects.ai/api/v1/simulations/{simulation_id}/status/" \
-H "Authorization: Api-Key YOUR_API_KEY"
curl -X GET "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/" \
-H "Authorization: Token YOUR_AUTH_TOKEN"
curl -X GET "https://api.vects.ai/api/v1/simulations/{simulation_id}/status/"
This endpoint supports anonymous access, allowing you to check status without authentication if you have the simulation ID.
Path Parameters
string
required
The unique identifier of the simulation returned when you created it
Example Request
curl -X GET "https://api.vects.ai/api/v1/simulations/sim_abc123def456/status/" \
-H "Authorization: Api-Key YOUR_API_KEY"
Response
string
The unique identifier of the simulation (“id”)
string
Current status of the simulation
queued: Waiting to be processedprocessing: Currently being generatedcompleted: Successfully completedfailed: Generation failed
string
Absolute URL to the final simulation (null unless
status == complete)string
ISO 8601 timestamp when the simulation was created
string
ISO 8601 timestamp when processing began (null if not started)
string
ISO 8601 timestamp when processing completed (null if not completed)
string
The original prompt used to generate the simulation
object
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:| 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
OK
Status retrieved successfully
Not Found
Simulation not found
Internal Server Error
Server error retrieving status
Polling Best Practices
When polling for status updates:- Start with short intervals: Poll every 5-10 seconds initially
- Increase intervals gradually: Move to 30-60 seconds for longer simulations
- Respect rate limits: Don’t exceed your API rate limits
- Use webhooks when possible: Consider using webhook notifications instead of polling
Next Steps
- Once status is
completed, retrieve results with the Results API - Learn about Risk Analysis for safety assessments
- Explore Urban Mobility MARL for real-time simulations