> ## Documentation Index > Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt > Use this file to discover all available pages before exploring further. # 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_ids` to score specific batches. Each must be in one of the model's source ledgers. - Provide `start_date` and/or `end_date` to 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. ## OpenAPI ````yaml POST /ledgers/{ledger_id}/score_sets openapi: 3.1.0 info: title: Mangrove - API version: 1.1.0 description: > ## Filtering and sorting List endpoints that accept `filter` take one query parameter per condition, written `filter[field][comparator]=value`, for example `filter[name][contains]=North`. The comparators are `eq`, `neq`, `gt`, `geq`, `lt`, `leq` and `contains`, and `filter[field]=value` is short for `eq`. Conditions combine with AND. `contains` matches part of the value, is case-sensitive, and applies only to text fields. An unknown field or comparator, a value that doesn't fit the field's type, or a list or object as the value returns 400 with a message naming the problem. Each list operation names its filterable fields; some take only `eq`, and say so. `sort` takes a comma-separated list of fields, for example `sort=-created_at,name`. Each field sorts ascending, or descending with a `-` prefix. Unknown sort fields are ignored. Sorting by `id` orders by the record's internal ID, not its friendly ID. Each list operation names its sortable fields. servers: - url: https://app.gomangrove.com/api/v1 security: - sec0: [] paths: /ledgers/{ledger_id}/score_sets: post: summary: Create a score set description: > 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_ids` to score specific batches. Each must be in one of the model's source ledgers. - Provide `start_date` and/or `end_date` to 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. operationId: create-score-set parameters: - $ref: '#/components/parameters/LedgerId' requestBody: required: true content: application/json: schema: type: object required: - model_id anyOf: - required: - reporting_period_id - required: - start_date - end_date properties: reporting_period_id: type: string description: >- 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. model_id: type: string description: >- 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. batch_ids: type: array description: >- 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. items: type: string start_date: type: string format: date description: >- 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_date: type: string format: date description: >- 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. workbook_tab_windows: type: object description: > 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. additionalProperties: type: object required: - start_date - end_date properties: start_date: type: string format: date description: First day of the sheet's first month. end_date: type: string format: date description: Last day of the sheet's final month. examples: Request Example: value: reporting_period_id: cirp_aBcD1234eFgH5678 model_id: mod_aBcD1234eFgH5678 With batch IDs: value: reporting_period_id: cirp_aBcD1234eFgH5678 model_id: mod_aBcD1234eFgH5678 batch_ids: - ba_aBcD1234eFgH5678 - ba_xYzW7890aBcD1234 With a shortened workbook sheet: value: reporting_period_id: cirp_aBcD1234eFgH5678 model_id: mod_aBcD1234eFgH5678 workbook_tab_windows: biogas_to_rng: start_date: '2025-07-01' end_date: '2025-12-31' With date range: value: reporting_period_id: cirp_aBcD1234eFgH5678 model_id: mod_aBcD1234eFgH5678 start_date: '2025-01-01' end_date: '2025-03-31' Ad-hoc window, no reporting period: value: model_id: mod_aBcD1234eFgH5678 start_date: '2025-01-01' end_date: '2025-03-31' responses: '202': description: The score calculation is queued. content: application/json: example: id: scr_aBcD1234eFgH5678 reporting_period_id: cirp_aBcD1234eFgH5678 model_id: mod_aBcD1234eFgH5678 ledger_id: led_aBcD1234eFgH5678 status: initialized score: null score_name: Carbon Intensity score_unit: kgCO2e/MJ reporting_period_label: 2025 Q1 (2025-01-01 - 2025-03-31) window_label: 2025 Q1 (2025-01-01 - 2025-03-31) start_date: '2025-01-01' end_date: '2025-03-31' model_label: Carbon Intensity Model error_message: null created_at: '2025-01-15T10:00:00.000Z' updated_at: '2025-01-15T10:00:00.000Z' schema: $ref: '#/components/schemas/ScoreSet' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Carbon intensity is not enabled for your account, or the token lacks the `write:ledger` scope. content: application/json: example: errors: - message: Carbon intensity feature is not enabled schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- The ledger, `model_id` or `reporting_period_id` does not exist in the account, `batch_ids` names an unknown batch, or the ledger is not a carbon intensity ledger. content: application/json: examples: Unknown ledger: value: errors: - message: Record not found Not a carbon intensity ledger: value: errors: - message: Carbon intensity ledger configuration not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- An invalid date, no window (neither `reporting_period_id` nor both dates), a model that does not produce a score, batches outside the model's source ledgers, no batches in the date range when a reporting period is given, or an invalid `workbook_tab_windows`. content: application/json: examples: Invalid date: value: errors: - message: Invalid date format No window: value: errors: - message: Start date can't be blank field: start_date code: blank - message: End date can't be blank field: end_date code: blank Batches not in model source ledgers: value: errors: - message: >- Batches 4521 do not belong to this model's source ledgers field: base code: >- Batches 4521 do not belong to this model's source ledgers schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: LedgerId: name: ledger_id in: path required: true description: The ledger's friendly ID (e.g. `led_aBcD1234eFgH5678`). schema: type: string schemas: ScoreSet: type: object properties: id: type: string example: scr_aBcD1234eFgH5678 reporting_period_id: type: - string - 'null' example: cirp_aBcD1234eFgH5678 model_id: type: - string - 'null' example: mod_aBcD1234eFgH5678 ledger_id: type: - string - 'null' example: led_aBcD1234eFgH5678 status: type: string enum: - initialized - running - completed - failed score: type: - string - 'null' description: >- The score as a decimal string (e.g. `"12.345"`; a whole number renders as `"12.0"`). Null until the calculation completes. score_name: type: - string - 'null' score_unit: type: - string - 'null' reporting_period_label: type: - string - 'null' description: >- The reporting period's label with its dates. Null for an ad-hoc score set; use `window_label`, which is always populated. window_label: type: string description: >- Human-readable label for the scored window, whether it came from a reporting period or an ad-hoc start/end range. start_date: type: - string - 'null' format: date end_date: type: - string - 'null' format: date model_label: type: - string - 'null' error_message: type: - string - 'null' description: >- 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. created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object required: - errors properties: errors: type: array items: type: object required: - message properties: message: type: string description: Human-readable error message field: type: string description: Attribute the error applies to (validation errors only) code: type: string description: Machine-readable error code (validation errors only) blocking: type: array description: >- Bounded preview of the records blocking a destroy (blocked-destroy errors only) items: $ref: '#/components/schemas/DeletionBlockingRecord' blocking_count: type: integer description: >- Total count of records blocking a destroy (blocked-destroy errors only) config_key: type: string description: >- The data feed source config setting to fix, when the error is on `config` (data feed source validation errors only) count: type: number description: >- The limit or comparison value the failed validation checked against, e.g. a maximum length or a numeric bound (validation errors only, when the validation has one) value: description: >- The rejected value, e.g. on an inclusion or uniqueness failure (validation errors only, when the validation reports one) DeletionBlockingRecord: type: object required: - type properties: type: type: string friendly_id: type: string name: type: - string - 'null' description: >- Display label, and the only identifier for records that have no friendly_id responses: Unauthorized: description: >- The API token is missing, invalid or expired. The body is empty, except for an expired token, which returns the error below. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: errors: - message: API token has expired securitySchemes: sec0: type: apiKey in: header name: Authorization x-bearer-format: '' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.