Create a score set
Initiates an asynchronous carbon intensity score calculation for the given ledger. Returns immediately with a score set in initialized status. Poll GET /ledgers/{ledger_id}/score_sets/{id} until status is completed or failed.
reporting_period_id is optional. When provided, the score set is scored against that reporting period’s window. When omitted, the score set is ad-hoc — supply start_date/end_date to define its window directly.
Batches to score can be specified in three ways:
- Provide
batch_idsto score specific batches. Each must be in one of the model’s source ledgers. - Provide
start_dateand/orend_dateto score every batch in the model’s source ledgers that overlaps that range. With a reporting period, the range only picks the batches (they need not fall inside the period, and the score window stays the period’s), and an empty result returns 422. Without one, the range is also the score window, and an empty result is allowed. - Omit both and no batches are scored: the calculation reads only the event-based inputs in the window. This holds with a reporting period too.
Requires carbon intensity to be enabled for your account (feature_carbon_intensity in GET /feature_flags); otherwise returns 403 “Carbon intensity feature is not enabled”. Requires the write:ledger token scope.
Authorizations
Path Parameters
The ledger's friendly ID (e.g. led_aBcD1234eFgH5678).
Body
- Option 1
- Option 2
The friendly ID of the carbon intensity reporting period to score against (e.g. cirp_aBcD1234eFgH5678). Optional. When omitted, the score set is ad-hoc and uses start_date/end_date as its window.
The friendly ID of the score-producing model to use (e.g. mod_aBcD1234eFgH5678). A missing or unknown model returns 404; a model that does not produce a score returns 422.
Optional explicit list of batch friendly IDs to score. When provided, these batches are scored directly; start_date/end_date then only define the window (they do not auto-select batches). An unknown ID returns 404; a batch outside the model's source ledgers returns 422.
Start of the score window. Required (with end_date) when reporting_period_id is omitted. When batch_ids is also omitted, auto-selects batches in this range. Must be a YYYY-MM-DD date; any other format is rejected with 422 rather than guessed at.
End of the score window. Required (with start_date) when reporting_period_id is omitted. When batch_ids is also omitted, auto-selects batches in this range. Must be a YYYY-MM-DD date; any other format is rejected with 422 rather than guessed at.
Optional per-sheet time windows for the model's Excel workbook. Keys are workbook tab keys derived from the sheet name (e.g. biogas_to_rng); omit a tab to leave it covering the full score window.
A windowed sheet writes a physically shorter table rather than one padded with zeros, which is what the workbook's own math requires when a sheet's equipment ran for only part of the reporting period. Bounds must be whole months and must fall within the score window. Generation fails if a window matches no selected batches or names an unknown tab.
Response
The score calculation is queued.
"scr_aBcD1234eFgH5678"
"cirp_aBcD1234eFgH5678"
"mod_aBcD1234eFgH5678"
"led_aBcD1234eFgH5678"
initialized, running, completed, failed The score as a decimal string (e.g. "12.345"; a whole number renders as "12.0"). Null until the calculation completes.
The reporting period's label with its dates. Null for an ad-hoc score set; use window_label, which is always populated.
Human-readable label for the scored window, whether it came from a reporting period or an ad-hoc start/end range.
Failure cause when status is failed — the model run's per-node error summary when it recorded any, otherwise the calculation task's message. Null otherwise.