Skip to content
TotalView API

Projects & Runs

A project is a renewable energy asset with a location, capacity, and technology. Queuing it produces a model run with full lifecycle impact results.

Creating a project

Section titled “Creating a project”
Terminal window
curl -X POST https://api.totalview.energy/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "project_name": "West Texas Solar",
    "latitude": 32.5, "longitude": -97.3,
    "nameplate_capacity": 100,
    "tech_type_id": "solar_ground",
    "sam_profile_flag": true,
    "eia_ba_code": "ERCO",
    "project_nerc_code": "US-TRE"
  }'

Technology types

Section titled “Technology types”
tech_type_idDescription
solar_groundGround-mount solar PV (default solar)
solar_rooftopRooftop solar PV (higher losses)
wind_onshoreOnshore wind (turbine auto-sized by capacity)
wind_offshoreOffshore wind

Required vs. optional

Section titled “Required vs. optional”

Required: project_name, latitude, longitude, nameplate_capacity (MW), tech_type_id.

Recommended: eia_ba_code and project_nerc_code — supplying these skips a geocoding lookup that can otherwise fail. sam_profile_flag: true generates an hourly generation profile via PySAM.

Regioneia_ba_codeproject_nerc_code
Texas / ERCOTERCOUS-TRE
CaliforniaCISOUS-CAL
PJMPJMUS-RFCE

Battery, PPA, existing-project, and custom-profile fields are documented in the create-project reference. For storage, see Battery Storage.

Queuing a run

Section titled “Queuing a run”
Terminal window
curl -X POST https://api.totalview.energy/api/v1/projects/$PROJECT_ID/queue \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'

start_date / end_date are auto-derived from the project type; existing projects without a profile require analysis_year. The run is asynchronous — poll GET /projects/{id}/runs/latest (202 = still running, 200 = done).

Updating a project

Section titled “Updating a project”

PATCH /projects/{id} accepts partial updates. The response reports fields_changed and results_invalidated — changing a results-affecting field (location, capacity, tech, battery, PPA) invalidates existing results and sets the project to config_updated. Pass "auto_queue": true to automatically enqueue a fresh run when that happens; the response then includes queued_model_run_id.

Cosmetic fields (name, city, county) never invalidate results.

Reading results

Section titled “Reading results”
Terminal window
curl https://api.totalview.energy/api/v1/projects/$PROJECT_ID/results \
  -H "Authorization: Bearer $TOKEN"

The headline value is Impacts.Cradle_to_Grave_Analysis.Total (DALYs / PDFs / USD). Generation shows fuel-mix displacement; Emissions breaks avoided emissions down by compartment. Full interpretation in LCIA Results.

403 means your access level is summary-only — partners and report recipients get a filtered view. Many projects at once? Use Batch Processing.

Next steps

Section titled “Next steps”