Simulation 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": {}
  }
}

GET

api

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 processed
processing: Currently being generated
completed: Successfully completed
failed: 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

Error details if status is failed

Show error properties

string

Human-readable error description

string

Machine-readable error code

object

Additional error context

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

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

Simulation Risk Analysis Simulation Results

Simulation APIs

Urban Mobility MARL

Risk Assessment

Overview

Authentication

Path Parameters

Example Request

Response

Example Responses

Queued Simulation

Processing Simulation

Completed Simulation

Failed Simulation

Processing Stages

Status Codes

Polling Best Practices

Next Steps

​Overview

​Authentication

​Path Parameters

​Example Request

​Response

​Example Responses

​Queued Simulation

​Processing Simulation

​Completed Simulation

​Failed Simulation

​Processing Stages

​Status Codes

​Polling Best Practices

​Next Steps

Overview

Authentication

Path Parameters

Example Request

Response

Example Responses

Queued Simulation

Processing Simulation

Completed Simulation

Failed Simulation

Processing Stages

Status Codes

Polling Best Practices

Next Steps