Submit Batch Projects

POST

/api/v1/batch

const url = 'https://api.totalview.energy/api/v1/batch';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"projects":[{"customer_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","project_name":"example","portfolio_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","latitude":1,"longitude":1,"state":"example","county":"example","city":"example","zip_code":"example","timezone":"example","project_nerc_code":"example","cod_date":"2026-04-15T12:00:00Z","decommision_date":"2026-04-15T12:00:00Z","nameplate_capacity":1,"gen_hour_profile_mw":[{"timestamp":"2026-04-15T12:00:00Z","value":1,"source":"example"}],"gen_aggregate_points":[{"period_start":"2026-04-15","period_end":"2026-04-15","sum_mwh":1,"granularity":"5min","source":"example"}],"sam_profile_flag":false,"poi_limit":1,"project_additional_load":0,"existing_project_flag":false,"tech_type_id":"example","ppa_flag":false,"ppa_percentage":1,"ppa_capacity":1,"battery_flag":false,"battery_capacity_mwh":1,"battery_duration_hours":1,"battery_charge_rate_mw":1,"battery_discharge_rate_mw":1,"battery_round_trip_eff":1,"battery_soc_min":1,"battery_chemistry":"lfp","battery_calendar_life_years":20,"battery_cycle_life":6000,"battery_augmentation_flag":false,"battery_depth_of_discharge":0.85,"eia_ba_code":"example"}],"callback_url":"example","priority":"high"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.totalview.energy/api/v1/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "projects": [ { "customer_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "project_name": "example", "portfolio_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "latitude": 1, "longitude": 1, "state": "example", "county": "example", "city": "example", "zip_code": "example", "timezone": "example", "project_nerc_code": "example", "cod_date": "2026-04-15T12:00:00Z", "decommision_date": "2026-04-15T12:00:00Z", "nameplate_capacity": 1, "gen_hour_profile_mw": [ { "timestamp": "2026-04-15T12:00:00Z", "value": 1, "source": "example" } ], "gen_aggregate_points": [ { "period_start": "2026-04-15", "period_end": "2026-04-15", "sum_mwh": 1, "granularity": "5min", "source": "example" } ], "sam_profile_flag": false, "poi_limit": 1, "project_additional_load": 0, "existing_project_flag": false, "tech_type_id": "example", "ppa_flag": false, "ppa_percentage": 1, "ppa_capacity": 1, "battery_flag": false, "battery_capacity_mwh": 1, "battery_duration_hours": 1, "battery_charge_rate_mw": 1, "battery_discharge_rate_mw": 1, "battery_round_trip_eff": 1, "battery_soc_min": 1, "battery_chemistry": "lfp", "battery_calendar_life_years": 20, "battery_cycle_life": 6000, "battery_augmentation_flag": false, "battery_depth_of_discharge": 0.85, "eia_ba_code": "example" } ], "callback_url": "example", "priority": "high" }'

Submit a batch of projects for processing.

Batch Processing Modes:

Single mode (<50 projects): Each project processed as individual AWS Batch job
Batch mode (>=50 projects): Projects grouped and processed in parallel within fewer jobs

Authorizations

OAuth2PasswordBearer

Request Body^required

application/json

BatchProjectSubmit

Schema for submitting multiple projects in a single batch.

object

projects

required

Projects

List of 1-1000 projects to process

Array<object>

>= 1 items <= 1000 items

ProjectCreate

Request schema for creating a new project.

object

customer_id

Any of:

string
null

string format: uuid

project_name

required

Project Name

string

portfolio_id

Any of:

string
null

string format: uuid

latitude

required

Latitude

number

longitude

required

Longitude

number

state

Any of:

string
null

string

county

Any of:

string
null

string

city

Any of:

string
null

string

zip_code

Any of:

string
null

string

timezone

Any of:

string
null

string

project_nerc_code

Any of:

string
null

string

cod_date

Any of:

string
null

string format: date-time

decommision_date

Any of:

string
null

string format: date-time

nameplate_capacity

required

Nameplate Capacity

number

gen_hour_profile_mw

Any of:

Array<object>
null

Array<object>

HourlyGenEntry

Hourly generation profile entry.

The optional source field records the provenance of the value (e.g., "metered", "sam_modeled", "gap_filled_zero"). The engine surfaces the per-source hour-count in the run summary’s GenerationMetadata.profile_source_breakdown so reviewers can audit which fraction of the profile is metered vs. simulated. Source is opaque — any string is allowed.

object

timestamp

required

Timestamp

string format: date-time

value

required

Any of:

number
null

number

source

Any of:

string
null

string

gen_aggregate_points

Any of:

Array<object>
null

Array<object>

AggregateGenPoint

A metered generation total over a time window.

Used when a customer can’t provide a full hourly profile but does have aggregate totals (monthly settlement, daily SCADA export, annual operational report). The engine combines these with a SAM-generated 8760 shape — preserving the SAM diurnal/seasonal pattern within each window while rescaling so the window sum matches sum_mwh exactly.

source is a free-text provenance tag carried through to ISO 14040 disclosure (e.g., "settlement", "scada_export", "operational_report").

object

period_start

required

Period Start

string format: date

period_end

required

Period End

string format: date

sum_mwh

required

Sum Mwh

number

granularity

required

Granularity

string

Allowed values: 5min 15min hourly daily weekly monthly quarterly annual

source

Any of:

string
null

string

sam_profile_flag

Sam Profile Flag

boolean

poi_limit

Any of:

number
null

number

project_additional_load

Any of:

number
null

number

existing_project_flag

Existing Project Flag

boolean

tech_type_id

required

Tech Type Id

Technology type: solar_ground, solar_rooftop, wind_onshore, or wind_offshore

string

ppa_flag

Any of:

boolean
null

boolean

ppa_percentage

Any of:

number
null

number

ppa_capacity

Any of:

number
null

number

battery_flag

Any of:

boolean
null

boolean

battery_capacity_mwh

Any of:

number
null

number

battery_duration_hours

Any of:

number
null

number

battery_charge_rate_mw

Any of:

number
null

number

battery_discharge_rate_mw

Any of:

number
null

number

battery_round_trip_eff

Any of:

number
null

number

battery_soc_min

Any of:

number
null

number

battery_chemistry

Any of:

string
null

string

battery_calendar_life_years

Any of:

number
null

number

battery_cycle_life

Any of:

integer
null

integer

battery_augmentation_flag

Any of:

boolean
null

boolean

battery_depth_of_discharge

Any of:

number
null

number

eia_ba_code

Any of:

string
null

string

callback_url

Any of:

string
null

string

priority

Priority

Processing priority

string

default: standard

Allowed values: high standard low

Responses

202

Successful Response

application/json

BatchSubmitResponse

Response after submitting a batch of projects.

object

batch_id

required

Batch Id

Unique batch identifier

string

project_count

required

Project Count

Number of projects in the batch

integer

project_ids

required

Project Ids

List of created project IDs

Array<string>

status

Status

Batch status (queued)

string

default: queued

queue_type

required

Queue Type

Processing type: ‘single’ (<50) or ‘batch’ (≥50)

string

Allowed values: single batch

estimated_completion_minutes

required

Estimated Completion Minutes

Estimated time to complete batch

integer

callback_url

Any of:

string
null

string

Example

{
  "status": "queued",
  "queue_type": "single"
}

422

Validation Error

application/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example ^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}

Submit Batch Projects

Authorizations

Request Body required

Responses

202

Example

422

Example generated

Request Body^required

Example ^generated