Skip to main content

Running a Simulation

This guide walks through running your first simulation using the SIR model with US population data.

1. Check available populations​

curl https://epyscenario-api.isi.it/api/v1/populations

Pick a population name from the list. We'll use United_States.

2. Check available presets​

curl https://epyscenario-api.isi.it/api/v1/models/presets

We'll use the SIR preset.

3. Send a simulation request​

curl -X POST https://epyscenario-api.isi.it/api/v1/simulations \
-H "Content-Type: application/json" \
-d '{
  "model": {
    "preset": "SIR",
    "parameters": {
      "transmission_rate": 0.3,
      "recovery_rate": 0.1
    }
  },
  "population": {
    "name": "United_States"
  },
  "simulation": {
    "start_date": "2024-01-01",
    "end_date": "2024-06-01",
    "Nsim": 10
  }
}'

4. Read the response​

The response contains metadata, results, and a status field.

{
  "simulation_id": "sim_c9617343b215",
  "status": "completed",
  "metadata": {
    "model_preset": "SIR",
    "compartments": ["Susceptible", "Infected", "Recovered"],
    "population_name": "United_States",
    "population_size": 338120586,
    "n_age_groups": 5,
    "start_date": "2024-01-01",
    "end_date": "2024-06-01",
    "n_simulations": 10,
    "dt": 1.0,
    "seed": null
  },
  "results": {
    "compartments": {
      "dates": ["2024-01-01", "2024-01-02", "..."],
      "data": {
        "Susceptible": {
          "total": {
            "0.5": [337330136.0, 334286966.0, "..."],
            "0.025": [337330089.45, 334285584.7, "..."],
            "0.975": [337330182.55, 334288347.3, "..."]
          }
        }
      }
    },
    "transitions": {
      "dates": ["2024-01-01", "2024-01-02", "..."],
      "data": {
        "Susceptible_to_Infected": {
          "total": {
            "0.5": [621391.0, 3043170.0, "..."],
            "0.025": [621344.45, 3041835.25, "..."],
            "0.975": [621437.55, 3044504.75, "..."]
          }
        }
      }
    }
  }
}

Results are organized as quantiles (median, confidence intervals) across simulation runs. Both compartments and transitions follow the same nested structure: name -> age_group -> quantile -> [values]. The total age group is the sum across all age groups.

5. Increase Nsim for production use​

Start with Nsim: 10 while testing, then increase to 100 or more for reliable estimates.

tip

Use the API Reference to build and send requests interactively without writing curl commands.