Scenarios & Profiles

Scenarios and profiles let you explore variants of a project without duplicating it.

• A scenario overrides project configuration — capacity, tech type, COD, battery, PPA settings.
• A profile is hourly generation data — an 8760-hour series, or P50/P75/P90 confidence variants.

A scenario can have multiple profiles; queuing all of them produces a comparable run group.

Scenarios

Create a variant — only the fields you override are supplied:

curl -X POST https://api.totalview.energy/api/v1/projects/$PROJECT_ID/scenarios \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "scenario_name": "150 MW + 2h battery",
    "nameplate_capacity": 150,
    "battery_flag": true,
    "battery_capacity_mwh": 300,
    "battery_duration_hours": 2
  }'

The response config_snapshot is the project base merged with your overrides. GET, PATCH, and DELETE follow the standard pattern (the default scenario can’t be deleted). POST .../scenarios/{id}/clone?new_name=… copies an existing scenario.

Profiles

Supply your own hourly generation instead of a SAM-generated one:

curl -X POST https://api.totalview.energy/api/v1/projects/$PROJECT_ID/profiles \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "profile_label": "P50",
    "source": "pvsyst",
    "gen_hour_profile_mw": [
      { "timestamp": "2024-01-01T00:00:00Z", "value": 0.0 },
      { "timestamp": "2024-01-01T01:00:00Z", "value": 0.0 }
    ]
  }'

Profile data format

gen_hour_profile_mw is an array of { timestamp, value }. Timestamps are ISO 8601 and contiguous (no gaps for existing projects); values are generation in MW (not MWh). Annual generation is computed for you. Use 8760 entries for a full year. Set is_primary: true to make a profile the default for auto-selection.

Queuing & comparing

Queue a specific scenario/profile — or every profile at once:

curl -X POST https://api.totalview.energy/api/v1/projects/$PROJECT_ID/queue-scenario \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{ "scenario_id": "…", "run_all_profiles": true }'

run_all_profiles: true returns a run_group_id tying the runs together. Retrieve a side-by-side comparison:

curl "https://api.totalview.energy/api/v1/projects/$PROJECT_ID/compare?run_group_id=$RUN_GROUP_ID" \
  -H "Authorization: Bearer $TOKEN"

The response lists each profile with its generation, DALYs, PDFs, USD, CO₂e, and health/biodiversity/economic breakdowns.

Next steps

• Projects & Runs · Impacts & Time Series · API Reference