Simulations

Run tax-benefit microsimulations on datasets. Simulations are processed asynchronously by background workers.

Note: Simulations use deterministic UUIDs based on inputs. Requesting the same simulation twice returns the cached result instead of running again.

List simulations

GET/simulations

Retrieve all simulations.

https://v2.api.policyengine.org/simulations

Get simulation

GET/simulations/:simulation_id

Retrieve a specific simulation and its status.

Path parameters

simulation_idUUID of the simulation

https://v2.api.policyengine.org/simulations/770e8400-e29b-41d4-a716-446655440000

Create simulation

POST/simulations

Create a new simulation. Returns immediately with pending status.

Request body

{
  "dataset_id": "4d5b4f7c-c7cf-4f49-8b59-a491e0adbf8d",
  "tax_benefit_model_version_id": "a8a20af0-b0bf-4b98-9e42-a62034f99da5",
  "policy_id": null,
  "dynamic_id": null
}

https://v2.api.policyengine.org/simulations

Request parameters

dataset_idUUID - Dataset to run simulation on

tax_benefit_model_version_idUUID - Model version to use

policy_idUUID | null - Optional policy reform

dynamic_idUUID | null - Optional behavioural response model

Response object

idUUID - Deterministic identifier

dataset_idUUID - Reference to dataset

policy_idUUID | null - Optional policy reform

dynamic_idUUID | null - Optional behavioural response

statusenum - pending | running | completed | failed

error_messagestring | null - Error details if failed

started_atdatetime | null - When processing started

completed_atdatetime | null - When processing finished

Status values

pendingQueued, waiting for worker

runningWorker is processing

completedSuccessfully finished

failedError occurred (see error_message)