Simulations

A Simulation is a runtime instance of one ready Simulator. It has its own state and a data-plane endpoint at https://api.continuouslabs.ai/sim/{id} that serves the Simulator’s API. Its clock stays fixed between explicit advances. Given the same requests and time advances from the same initial state, a Simulation returns the same responses and ends in the same visible state.

​

When to use one

Start a Simulation whenever an agent needs a system to act on. Start several from one Simulator to run scenarios in parallel; each keeps its own state.

​

Lifecycle

Statuses are running, paused, and stopped. Create and fork return running. Running and paused Simulations serve requests. paused means the Simulation was idle and the platform paused it; the next request wakes it. There is no pause endpoint. An idle Simulation pauses after a period of inactivity. Inactivity never stops it. A World member pauses the same way. Stop saves the Simulation’s state. Its endpoint, its steps, and fork answer 409 simulation_stopped until you start it again. Stopping a stopped Simulation returns it unchanged. A stopped Simulation does not count toward the workspace’s active Simulation limit. Start restores a stopped Simulation from its saved state and needs a free Simulation slot. The response includes the Simulation’s token, which stop and start do not change. Starting a running or paused Simulation returns its actual status and token. Nothing deletes a Simulation automatically; delete removes it and its saved state. name is a label; its field constraints are in the generated create endpoint. Omit it for a generated name. Names need not be unique; the sim_ ID is the identity.

​

Credentials

Each Simulation has one token. Create, fork, and start return it; ordinary get, list, and event responses omit credentials. Send it in X-Continuous-Simulation-Token. The token does not expire. Pause, stop, and restart keep it; a stopped Simulation’s endpoint answers 409 simulation_stopped until start. GET /v1/simulations/{id}/token returns the token, even while the Simulation is stopped. Token responses also include the deprecated expires_at field, which is always null. To rotate the token, send POST /v1/simulations/{id}/token/regenerate with an Idempotency-Key header. It works in any status and returns the new token. Once it commits, the previous token answers 401 auth_invalid with X-Continuous-Simulation-Token-Rejected: true, so every client that holds it must retrieve the new one. A repeated key returns the same token while it is current; after a later regeneration, it answers 409 simulation_token_regeneration_superseded. Deleting the Simulation ends its token. See the quickstart for a complete sequence that creates a Simulation, sends requests, retrieves and regenerates its token, and deletes it.

​

Advance time

Set optional start_time when you create a Simulation. Omit it to use January 1, 2024, at 00:00 UTC. Times use RFC 3339 with up to millisecond precision. Reads expose the initial and current clock and any active advance. Send POST /v1/simulations/{id}/advance-time with an Idempotency-Key header and an absolute to timestamp. The response is a durable operation that you can poll. Repeating the same key and target returns the same operation. Time can only move forward; fork an earlier step to return to earlier state. An advance runs scheduled events through the target time. Each event sees its own due time. For example, an advance across three billing periods can produce three renewal invoices. Equal-time events run in the order they were scheduled. The clock reaches the target after all due events finish. A failed handler rolls back the entire local advance. Stop, pause, wake, and restart preserve the clock and pending events. Simulation time does not affect the Simulation token or platform runtime timeouts. While an advance is active, conflicting lifecycle calls, including deletion, return 409 clock_conflict. A handler failure ends a standalone advance and releases that reservation. A World can have committed members after a partial failure, so its deletion instead cancels and drains the coordinated advance. Poll GET /v1/simulations/{id}/advances/{advance_id} for durable clock progress. Read the committed trace with GET /v1/simulations/{id}/advances/{advance_id}/events; it uses cursor pagination.

​

Steps and forks

A step is one committed state change. A writing request creates one step; a request that only reads creates none. A successful time advance creates one step for all its events and its final clock. A clock-only change also creates a step. An advance that changes nothing creates none. Events scheduled for the current time run before the next request, in an advance step of their own that no advance identifies. Step metadata identifies the action and clock bounds. Request labels use the HTTP method and path without the query string, for example POST /v1/widgets. An advance identifies its operation and ordered event trace. GET /v1/simulations/{id}/steps lists steps for a running or paused Simulation, paginated. Fork with POST /v1/simulations/{id}/fork. Omit at_step to fork the latest state, or pass a listed step value to start the child from the state after that step. Explicit zero selects the branch’s initial state. An at_step that is not a recorded step answers 422 validation. The child inherits the selected clock and pending events. Its later events and state changes are independent of the parent. It keeps its own Simulation-ID RNG seed, so branches can produce different random outcomes. You can fork before or after an advance; use smaller advances when you need finer fork points. Stop and restart retain the recorded fork points and their historical state. The source must be running or paused; a stopped source answers 409 simulation_stopped. The source is not changed. The child is a new running Simulation with parent_id set, its own endpoint, and a usable token. Forks count toward the active Simulation limit. You can fork a World member.

​

Operations

• Create POST /v1/simulations with simulator_id, optional name, and optional start_time.
• Get GET /v1/simulations/{id}.
• List GET /v1/simulations with status and simulator_id filters.
• Stop POST /v1/simulations/{id}/stop.
• Start POST /v1/simulations/{id}/start.
• Advance time POST /v1/simulations/{id}/advance-time.
• Steps GET /v1/simulations/{id}/steps.
• Fork POST /v1/simulations/{id}/fork.
• Current token GET /v1/simulations/{id}/token.
• Regenerate token POST /v1/simulations/{id}/token/regenerate.
• Delete DELETE /v1/simulations/{id}.

Stop, start, advance time, and delete a World member through its World. Those calls on the member answer 409 simulation_world_owned. A member detached from its World is a standalone Simulation.