> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engrate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Calculate Tariff

> Calculate costs for a [Tariff](/api-reference/cost-of-energy/models/tariff).

Executes the calculation pipeline for each tariff component that is active within the requested period. The caller must supply data for every dataset required by the active components, either as inline `time_series`, persisted `profiles`, or a combination of both. Dataset names must not overlap between the two inputs.



## OpenAPI

````yaml /openapi.json post /cost-of-energy/v1/calculate
openapi: 3.1.0
info:
  title: Engrate API
  version: 1.0.0
servers:
  - url: https://api.engrate.io
security:
  - apiKeyAuth: []
paths:
  /cost-of-energy/v1/calculate:
    post:
      summary: Calculate Tariff
      description: >-
        Calculate costs for a
        [Tariff](/api-reference/cost-of-energy/models/tariff).


        Executes the calculation pipeline for each tariff component that is
        active within the requested period. The caller must supply data for
        every dataset required by the active components, either as inline
        `time_series`, persisted `profiles`, or a combination of both. Dataset
        names must not overlap between the two inputs.
      operationId: calculate_tariff_cost_of_energy_v1_calculate_post
      parameters:
        - description: >-
            When true, the response includes all intermediate pipeline time
            series (e.g. hourly-power-offtake, monthly-peak) in addition to the
            final cost. When false (default), only the cost time series is
            returned per component.
          in: query
          name: include_intermediate_time_series
          required: false
          schema:
            default: false
            description: >-
              When true, the response includes all intermediate pipeline time
              series (e.g. hourly-power-offtake, monthly-peak) in addition to
              the final cost. When false (default), only the cost time series is
              returned per component.
            title: Include intermediate time series
            type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateTariffRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateTariffResponse'
          description: Successful Response
        '400':
          description: The request is well-formed but cannot be fulfilled.
        '404':
          description: A referenced resource was not found.
        '422':
          description: The request body failed schema validation.
components:
  schemas:
    CalculateTariffRequest:
      example:
        end_time: '2026-01-01T00:30:00+01:00'
        profiles:
          - name: quarter-hourly-day-ahead-price-se1
            profile_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        start_time: '2026-01-01T00:00:00+01:00'
        tariff_id: 123e4567-e89b-12d3-a456-426614174000
        time_series:
          - name: quarter-hourly-energy-offtake
            values:
              - 1.5
              - 1.2
      properties:
        end_time:
          description: >-
            End of the calculation period (exclusive). Must include timezone
            offset and be after start_time. For correct monthly/daily bucketing,
            align to local midnight in the tariff's timezone.
          format: date-time
          title: End Time
          type: string
        profiles:
          anyOf:
            - items:
                $ref: '#/components/schemas/InputProfile'
              type: array
            - type: 'null'
          description: >-
            Profile references for datasets. Each entry maps a dataset to a
            persisted profile UUID. Can be combined with time_series.
          title: Profiles
        start_time:
          description: >-
            Start of the calculation period (inclusive). Must include timezone
            offset. For correct monthly/daily bucketing, align to local midnight
            in the tariff's timezone (e.g. 2026-01-01T00:00:00+01:00 for
            Europe/Stockholm).
          format: date-time
          title: Start Time
          type: string
        tariff_id:
          description: ID of the tariff to calculate.
          format: uuid
          title: Tariff Id
          type: string
        time_series:
          anyOf:
            - items:
                $ref: '#/components/schemas/InputTimeSeries'
              type: array
            - type: 'null'
          description: >-
            Input time series data for each dataset required by the tariff's
            active components. Can be combined with profiles.
          title: Time Series
      required:
        - end_time
        - start_time
        - tariff_id
      title: CalculateTariffRequest
      type: object
    CalculateTariffResponse:
      example:
        components:
          - end_time: '2026-01-01T00:30:00+01:00'
            name: Energiskatt
            start_time: '2026-01-01T00:00:00+01:00'
            time_series:
              - name: cost
                resolution: quarter_hourly
                unit: SEK
                values:
                  - 0.54
                  - 0.432
      properties:
        components:
          description: >-
            Results per tariff component that is active within the requested
            period.
          items:
            $ref: '#/components/schemas/CalculateComponentResult'
          title: Components
          type: array
      required:
        - components
      title: CalculateTariffResponse
      type: object
    InputProfile:
      description: A reference to a persisted profile to use as input for a dataset.
      example:
        name: quarter-hourly-day-ahead-price-se1
        profile_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      properties:
        name:
          description: Dataset identifier.
          title: Name
          type: string
        profile_id:
          description: UUID of the persisted profile to use as input for this dataset.
          format: uuid
          title: Profile Id
          type: string
      required:
        - name
        - profile_id
      title: InputProfile
      type: object
    InputTimeSeries:
      description: >-
        A time series of data for a registered dataset that is input for a
        tariff component.


        Use ``null`` in the values array to represent absent values.
      example:
        name: quarter-hourly-energy-offtake
        values:
          - 1.5
          - 1.2
      properties:
        name:
          description: Dataset identifier.
          title: Name
          type: string
        values:
          description: >-
            Ordered values aligned to the implicit timestamp grid. Use null for
            absent values.
          items:
            anyOf:
              - type: number
              - type: 'null'
          title: Values
          type: array
      required:
        - name
        - values
      title: InputTimeSeries
      type: object
    CalculateComponentResult:
      example:
        end_time: '2026-01-01T00:30:00+01:00'
        name: Energiskatt
        start_time: '2026-01-01T00:00:00+01:00'
        time_series:
          - name: cost
            resolution: quarter_hourly
            unit: SEK
            values:
              - 0.54
              - 0.432
      properties:
        end_time:
          description: >-
            Actual end of the data range (after clipping to the component's
            applicable window).
          format: date-time
          title: End Time
          type: string
        name:
          title: Name
          type: string
        start_time:
          description: >-
            Actual start of the data range (after clipping to the component's
            applicable window).
          format: date-time
          title: Start Time
          type: string
        time_series:
          description: >-
            Calculated time series for this component. By default only the final
            cost time series is included. Pass
            include_intermediate_time_series=true to also get intermediate
            pipeline outputs.
          items:
            $ref: '#/components/schemas/CalculatedTimeSeries'
          title: Time Series
          type: array
      required:
        - end_time
        - name
        - start_time
        - time_series
      title: CalculateComponentResult
      type: object
    CalculatedTimeSeries:
      description: >-
        A named time series returned from a calculation, with explicit
        resolution and unit.
      example:
        name: cost
        resolution: quarter_hourly
        unit: SEK
        values:
          - 0.54
          - 0.432
      properties:
        name:
          description: Time series identifier.
          title: Name
          type: string
        resolution:
          $ref: '#/components/schemas/Resolution'
          description: Temporal resolution of the time series.
        unit:
          $ref: '#/components/schemas/Unit'
          description: Unit of the time series values.
        values:
          description: >-
            Ordered values aligned to the implicit timestamp grid. Uses null for
            absent values.
          items:
            anyOf:
              - type: number
              - type: 'null'
          title: Values
          type: array
      required:
        - name
        - resolution
        - unit
        - values
      title: CalculatedTimeSeries
      type: object
    Resolution:
      description: >-
        Temporal resolution


        ### Available resolutions


        - **quarter_hourly** — 15-minute resolution


        - **hourly** — 60-minute resolution


        - **daily** — Daily resolution in *calendar* days, not necessarily
        exactly 24 hours, depending on daylight savings etc


        - **weekly** — Weekly resolution in *calendar* weeks, not necessarily
        exactly 24 * 7 hours, depending on daylight savings etc


        - **monthly** — Monthly resolution in *calendar* months, taking into
        account things like daylight savings and leap year calculations


        - **yearly** — Annual resolution in *calendar* years, taking into
        account things like daylight savings and leap year calculations
      enum:
        - quarter_hourly
        - hourly
        - daily
        - weekly
        - monthly
        - yearly
      title: Resolution
      type: string
    Unit:
      description: >-
        Units indicate, well, the unit of values. These are used in places like
        [Datasets](/api-reference/cost-of-energy/models/dataset) and
        [Levels](/api-reference/cost-of-energy/models/level) to indicate the
        unit the data is in.


        ### Available units


        - **A** — Current in Amperes


        - **kV** — Voltage in kilo volts


        - **kW** — Power in kilo watts


        - **kWh** — Energy in kilo watt hours


        - **hours** — Time in hours


        - **SEK** — Monetary amount in SEK


        - **NOK** — Monetary amount in NOK


        - **EUR** — Monetary amount in EUR


        - **SEK_per_kWh** — Monetary rate in SEK per kWh


        - **SEK_per_kW** — Monetary rate in SEK per kW


        - **NOK_per_kWh** — Monetary rate in NOK per kWh


        - **NOK_per_kW** — Monetary rate in NOK per kW


        - **EUR_per_kWh** — Monetary rate in EUR per kWh


        - **EUR_per_kW** — Monetary rate in EUR per kW


        - **%** — Percentage, as a float, where 1.0 represents 100%
      enum:
        - A
        - kV
        - kW
        - kWh
        - hours
        - SEK
        - NOK
        - EUR
        - SEK_per_kWh
        - SEK_per_kW
        - NOK_per_kWh
        - NOK_per_kW
        - EUR_per_kWh
        - EUR_per_kW
        - '%'
      title: Unit
      type: string
  securitySchemes:
    apiKeyAuth:
      in: header
      name: Authorization
      type: apiKey

````