Simulation Results

curl --request GET \
  --url https://api.vects.ai/api/v1/simulations/{simulation_id}/

{
  "200": {},
  "202": {},
  "404": {},
  "410": {},
  "500": {},
  "simulation_id": "<string>",
  "status": "<string>",
  "metadata": {
    "metadata.prompt": "<string>",
    "metadata.created_at": "<string>",
    "metadata.completed_at": "<string>",
    "metadata.generation_time": 123,
    "metadata.settings": {}
  },
  "environment": {
    "environment.bounds": {},
    "environment.terrain": {},
    "environment.weather": {},
    "environment.lighting": {}
  },
  "actors": [
    {
      "actors[].id": "<string>",
      "actors[].type": "<string>",
      "actors[].position": [
        {}
      ],
      "actors[].properties": {},
      "actors[].behavior": {},
      "actors[].model": {}
    }
  ],
  "features": [
    {
      "features[].id": "<string>",
      "features[].type": "<string>",
      "features[].geometry": {},
      "features[].properties": {}
    }
  ],
  "assets": {
    "assets.models": [
      {}
    ],
    "assets.textures": [
      {}
    ],
    "assets.sounds": [
      {}
    ],
    "assets.animations": [
      {}
    ]
  }
}

GET

api

simulations

{simulation_id}

Simulation Results

curl --request GET \
  --url https://api.vects.ai/api/v1/simulations/{simulation_id}/

{
  "200": {},
  "202": {},
  "404": {},
  "410": {},
  "500": {},
  "simulation_id": "<string>",
  "status": "<string>",
  "metadata": {
    "metadata.prompt": "<string>",
    "metadata.created_at": "<string>",
    "metadata.completed_at": "<string>",
    "metadata.generation_time": 123,
    "metadata.settings": {}
  },
  "environment": {
    "environment.bounds": {},
    "environment.terrain": {},
    "environment.weather": {},
    "environment.lighting": {}
  },
  "actors": [
    {
      "actors[].id": "<string>",
      "actors[].type": "<string>",
      "actors[].position": [
        {}
      ],
      "actors[].properties": {},
      "actors[].behavior": {},
      "actors[].model": {}
    }
  ],
  "features": [
    {
      "features[].id": "<string>",
      "features[].type": "<string>",
      "features[].geometry": {},
      "features[].properties": {}
    }
  ],
  "assets": {
    "assets.models": [
      {}
    ],
    "assets.textures": [
      {}
    ],
    "assets.sounds": [
      {}
    ],
    "assets.animations": [
      {}
    ]
  }
}

Overview

The Simulation Results API provides access to the complete generated simulation data, including 3D models, agent behaviors, terrain information, and interactive elements. This endpoint returns comprehensive simulation data that can be used for visualization, analysis, or further processing.

Authentication

curl -X GET "https://api.vects.ai/api/v1/simulations/{simulation_id}/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

This endpoint supports anonymous access for completed simulations, allowing you to retrieve results without authentication if you have the simulation ID.

Path Parameters

simulation_id

string

required

The unique identifier of the completed simulation

Query Parameters

format

string

default:"json"

Response format: json, geojson, gltf, fbx

include_assets

boolean

default:"true"

Whether to include 3D model assets and textures in the response

compression

string

default:"gzip"

Compression format: none, gzip, brotli

Example Requests

curl -X GET "https://api.vects.ai/api/v1/simulations/sim_abc123def456/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Response (JSON Format)

simulation_id

string

The unique identifier of the simulation (“id”)

status

string

Current status (should be completed for successful retrieval)

metadata

object

Simulation metadata and configuration

Show metadata properties

metadata.prompt

string

Original prompt used to generate the simulation

metadata.created_at

string

ISO 8601 timestamp when simulation was created

metadata.completed_at

string

ISO 8601 timestamp when simulation was completed

metadata.generation_time

integer

Total generation time in seconds

metadata.settings

object

Simulation settings used during generation

environment

object

Environment and terrain data

Show environment properties

environment.bounds

object

Geographic bounds of the simulation area

environment.terrain

object

Terrain mesh and elevation data

environment.weather

object

Weather conditions and atmospheric settings

environment.lighting

object

Lighting configuration and time of day

actors

array

Array of all actors (agents) in the simulation

Show actor properties

actors[].id

string

Unique identifier for the actor

actors[].type

string

Actor type: pedestrian, vehicle, building, object

actors[].position

array

3D position coordinates [x, y, z]

actors[].properties

object

Actor-specific properties and attributes

actors[].behavior

object

Behavioral configuration and AI parameters

actors[].model

object

3D model and visual representation data

features

array

Geographic and structural features

Show feature properties

features[].id

string

Unique identifier for the feature

features[].type

string

Feature type: building, road, landmark, vegetation

features[].geometry

object

GeoJSON geometry defining the feature shape

features[].properties

object

Feature-specific properties and metadata

assets

object

3D models, textures, and other simulation assets

Show assets properties

assets.models

array

Array of 3D model files and references

assets.textures

array

Texture files and material definitions

assets.sounds

array

Audio files for environmental sounds

assets.animations

array

Animation sequences for dynamic elements

Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "metadata": {
    "prompt": "Create a busy downtown intersection with pedestrians crossing, cars waiting at traffic lights, and a food truck on the corner",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:42Z",
    "generation_time": 342,
    "settings": {
      "max_agents": 100,
      "simulation_duration": 300,
      "environment_type": "urban",
      "weather_conditions": "clear"
    }
  },
  "environment": {
    "bounds": {
      "min_lat": 37.7749,
      "max_lat": 37.7759,
      "min_lng": -122.4194,
      "max_lng": -122.4184,
      "min_elevation": 0,
      "max_elevation": 15
    },
    "terrain": {
      "mesh_url": "https://assets.vects.ai/sim_abc123def456/terrain.gltf",
      "elevation_data": "https://assets.vects.ai/sim_abc123def456/elevation.tif"
    },
    "weather": {
      "condition": "clear",
      "temperature": 22,
      "humidity": 65,
      "wind_speed": 5
    },
    "lighting": {
      "time_of_day": "14:30",
      "sun_position": [45, 180],
      "ambient_intensity": 0.4
    }
  },
  "actors": [
    {
      "id": "actor_001",
      "type": "pedestrian",
      "position": [37.7754, -122.4189, 1.7],
      "properties": {
        "age": "adult",
        "gender": "female",
        "clothing": "casual",
        "walking_speed": 1.2
      },
      "behavior": {
        "goal": "cross_street",
        "path": [[37.7754, -122.4189], [37.7754, -122.4187]],
        "state": "walking"
      },
      "model": {
        "mesh_url": "https://assets.vects.ai/models/pedestrian_female_01.gltf",
        "animations": ["walk", "idle", "look_around"]
      }
    },
    {
      "id": "actor_002",
      "type": "vehicle",
      "position": [37.7752, -122.4190, 0.5],
      "properties": {
        "vehicle_type": "sedan",
        "color": "blue",
        "license_plate": "ABC123"
      },
      "behavior": {
        "goal": "proceed_straight",
        "state": "waiting_at_light",
        "speed": 0
      },
      "model": {
        "mesh_url": "https://assets.vects.ai/models/sedan_blue.gltf",
        "animations": ["idle", "drive"]
      }
    }
  ],
  "features": [
    {
      "id": "feature_001",
      "type": "building",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[[37.7750, -122.4192], [37.7750, -122.4188], [37.7756, -122.4188], [37.7756, -122.4192], [37.7750, -122.4192]]]
      },
      "properties": {
        "height": 25,
        "building_type": "commercial",
        "floors": 6
      }
    },
    {
      "id": "feature_002",
      "type": "road",
      "geometry": {
        "type": "LineString",
        "coordinates": [[37.7748, -122.4189], [37.7760, -122.4189]]
      },
      "properties": {
        "road_type": "street",
        "lanes": 2,
        "speed_limit": 25
      }
    }
  ],
  "assets": {
    "models": [
      {
        "id": "terrain_mesh",
        "url": "https://assets.vects.ai/sim_abc123def456/terrain.gltf",
        "format": "gltf",
        "size_mb": 2.4
      }
    ],
    "textures": [
      {
        "id": "asphalt_texture",
        "url": "https://assets.vects.ai/textures/asphalt_01.jpg",
        "resolution": "1024x1024"
      }
    ],
    "sounds": [
      {
        "id": "traffic_ambient",
        "url": "https://assets.vects.ai/sounds/traffic_ambient.mp3",
        "duration": 120
      }
    ]
  }
}

Export Formats

GeoJSON Format

When format=geojson, the response contains geographic data in GeoJSON format:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-122.4189, 37.7754]
      },
      "properties": {
        "type": "pedestrian",
        "id": "actor_001",
        "behavior": "walking"
      }
    }
  ]
}

3D Model Formats

When format=gltf or format=fbx, the response includes download URLs for 3D model files:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "format": "gltf",
  "download_url": "https://assets.vects.ai/sim_abc123def456/complete_scene.gltf",
  "assets": {
    "textures": "https://assets.vects.ai/sim_abc123def456/textures.zip",
    "animations": "https://assets.vects.ai/sim_abc123def456/animations.zip"
  },
  "expires_at": "2024-01-16T10:35:42Z"
}

Status Codes

200

Simulation results retrieved successfully

202

Accepted

Simulation is still processing (not yet completed)

404

Not Found

Simulation not found

410

Gone

Simulation results have expired and are no longer available

500

Internal Server Error

Server error retrieving results

Data Retention

Simulation results are stored for 30 days after completion
3D model assets are available for download for 7 days
Premium users get extended retention periods
Enterprise users can configure custom retention policies

Integration Examples

Unity Integration

// C# example for Unity
public async Task<SimulationData> LoadSimulation(string simulationId)
{
    var client = new HttpClient();
    client.DefaultRequestHeaders.Add("Authorization", "Api-Key YOUR_API_KEY");
    
    var response = await client.GetAsync($"https://api.vects.ai/api/v1/simulations/{simulationId}/");
    var json = await response.Content.ReadAsStringAsync();
    
    return JsonUtility.FromJson<SimulationData>(json);
}

Web Visualization

// JavaScript example for web applications
async function loadSimulation(simulationId) {
    const response = await fetch(`https://api.vects.ai/api/v1/simulations/${simulationId}/`, {
        headers: {
            'Authorization': 'Api-Key YOUR_API_KEY'
        }
    });
    
    const simulationData = await response.json();
    
    // Load into Three.js scene
    loadActorsIntoScene(simulationData.actors);
    loadEnvironmentIntoScene(simulationData.environment);
}

Next Steps

Learn about Risk Analysis to add safety assessments
Explore Urban Mobility MARL for real-time simulations
Check out integration guides for popular 3D engines and frameworks

Simulation Status Urban Mobility MARL WebSocket

​Overview

​Authentication

​Path Parameters

​Query Parameters

​Example Requests

​Response (JSON Format)

​Example Response

​Export Formats

​GeoJSON Format

​3D Model Formats

​Status Codes

​Data Retention

​Integration Examples

​Unity Integration

​Web Visualization

​Next Steps

Overview

Authentication

Path Parameters

Query Parameters

Example Requests

Response (JSON Format)

Example Response

Export Formats

GeoJSON Format

3D Model Formats

Status Codes

Data Retention

Integration Examples

Unity Integration

Web Visualization

Next Steps