> ## 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.

# Cost of Energy Quickstart

> Go from zero to a working cost calculation in minutes.

This guide walks you through the Cost of Energy API end-to-end: authenticate, find tariffs for a system operator, inspect a tariff component, and run a calculation that returns a step-by-step cost breakdown.

<Note>
  **AI-assisted development**

  The Cost of Energy API is designed to work with AI tools. Two ways to get started:

  <Columns cols={2}>
    <Card title="MCP Integration" icon="sparkles" href="/guides/mcp">
      Connect Claude, Cursor, or VS Code directly to the API
    </Card>

    <Card title="llms.txt" icon="robot" href="https://docs.engrate.io/llms.txt">
      Give your AI tool full API context in one file
    </Card>
  </Columns>
</Note>

## Prerequisites

You need an API key. Sign up at [console.engrate.io](https://console.engrate.io) and generate one.

<Steps>
  <Step title="Find a system operator">
    Look up Swedish DSOs (system operators) using the Core API. Here we search by name:

    <CodeGroup>
      ```bash Request theme={null}
      curl --request GET \
        --url "https://api.engrate.io/core/v1/parties?role=system_operator&country=SE&name=Ellevio" \
        --header "authorization: $API_KEY" \
        --header "content-type: application/json"
      ```

      ```json Response theme={null}
      {
        "parties": [
          {
            "id": "0199c317-25ec-7cf7-94cc-32a39f068433",
            "name": "Ellevio AB",
            "countries": ["SE"],
            "extra_ids": [
              { "kind": "eic", "value": "46X000000000245K" },
              { "kind": "se.ediel", "value": "24200" }
            ]
          }
        ]
      }
      ```
    </CodeGroup>

    Copy the `id` — you'll use it to find tariffs in the next step.
  </Step>

  <Step title="List tariffs for the operator">
    Fetch tariffs offered by that system operator:

    <CodeGroup>
      ```bash Request theme={null}
      curl --request GET \
        --url "https://api.engrate.io/cost-of-energy/v1/tariffs?system_operator_id=0199c317-25ec-7cf7-94cc-32a39f068433" \
        --header "authorization: $API_KEY" \
        --header "content-type: application/json"
      ```

      ```json Response theme={null}
      {
        "tariffs": [
          {
            "id": "0199c317-25ec-7cf7-94cc-32a39f068433",
            "name": "Säkringsabonnemang - 20 A",
            "summary": "Fuse-based tariff for 20A with energy tax and monthly subscription fee.",
            "available_from": "2024-01-01T00:00:00+01:00",
            "eligibility": {
              "type": "system_operator",
              "fuse_size": { "value": 20.0, "unit": "A" },
              "metering_grid_area_ids": ["..."],
              "other": ["fuse_based"]
            },
            "tariff_components": [ ... ]
          }
        ]
      }
      ```
    </CodeGroup>

    Each tariff has a `name`, `summary`, `eligibility` criteria, and a list of `tariff_components`. Copy the `id` of the tariff you want to inspect.
  </Step>

  <Step title="Fetch the full tariff">
    Get the complete tariff with all its calculation pipelines:

    <CodeGroup>
      ```bash Request theme={null}
      curl --request GET \
        --url "https://api.engrate.io/cost-of-energy/v1/tariffs/0199c317-25ec-7cf7-94cc-32a39f068433" \
        --header "authorization: $API_KEY" \
        --header "content-type: application/json"
      ```

      ```json Response theme={null}
      {
        "id": "0199c317-25ec-7cf7-94cc-32a39f068433",
        "name": "Säkringsabonnemang - 20 A",
        "summary": "Fuse-based tariff for 20A with energy tax and monthly subscription fee.",
        "available_from": "2024-01-01T00:00:00+01:00",
        "eligibility": {
          "type": "system_operator",
          "fuse_size": { "value": 20.0, "unit": "A" },
          "metering_grid_area_ids": ["..."],
          "other": ["fuse_based"]
        },
        "tariff_components": [
          {
            "name": "Energiskatt",
            "applicable_from": "2026-01-01T00:00:00+01:00",
            "datasets": [
              {
                "id": "quarter-hourly-energy-offtake",
                "resolution": "quarter_hourly",
                "unit": "kWh"
              }
            ],
            "functions": [
              {
                "type": "multiply",
                "left": {
                  "id": "quarter-hourly-energy-offtake",
                  "resolution": "quarter_hourly",
                  "unit": "kWh"
                },
                "right": { "value": 0.36, "unit": "SEK_per_kWh" },
                "output": {
                  "id": "cost",
                  "resolution": "quarter_hourly",
                  "unit": "SEK"
                }
              }
            ],
            "cost": { "id": "cost", "resolution": "quarter_hourly", "unit": "SEK" }
          },
          {
            "name": "Abonnemangsavgift",
            "applicable_from": "2025-01-01T00:00:00+01:00",
            "datasets": [],
            "functions": [
              {
                "type": "constant",
                "value": { "value": 187.5, "unit": "SEK" },
                "resolution": "monthly",
                "output": { "id": "cost", "resolution": "monthly", "unit": "SEK" }
              }
            ],
            "cost": { "id": "cost", "resolution": "monthly", "unit": "SEK" }
          }
        ]
      }
      ```
    </CodeGroup>

    This is the full tariff with its **tariff components** — the individual cost items like energy tax, subscription fees, or transfer charges. Each component includes a machine-readable [calculation pipeline](/api-reference/cost-of-energy/calculation-pipeline) that describes exactly how to compute the cost.

    Notice the `datasets` field on each component — these are the inputs the pipeline needs. The `Energiskatt` component requires `quarter-hourly-energy-offtake` (consumption data in kWh), while `Abonnemangsavgift` requires no input data at all (it's a fixed monthly fee).
  </Step>

  <Step title="Calculate costs">
    Call the Calculate endpoint with the tariff ID and the required dataset(s). Here we calculate for a 30-minute window with two quarter-hourly consumption readings:

    <CodeGroup>
      ```bash Request theme={null}
      curl --request POST \
        --url "https://api.engrate.io/cost-of-energy/v1/calculate" \
        --header "authorization: $API_KEY" \
        --header "content-type: application/json" \
        --data '{
          "tariff_id": "0199c317-25ec-7cf7-94cc-32a39f068433",
          "start_time": "2026-01-01T00:00:00+01:00",
          "end_time": "2026-01-01T00:30:00+01:00",
          "time_series": [
            {
              "name": "quarter-hourly-energy-offtake",
              "values": [1.5, 1.2]
            }
          ]
        }'
      ```

      ```json Response theme={null}
      {
        "components": [
          {
            "name": "Energiskatt",
            "start_time": "2026-01-01T00:00:00+01:00",
            "end_time": "2026-01-01T00:30:00+01:00",
            "time_series": [
              {
                "name": "cost",
                "resolution": "quarter_hourly",
                "unit": "SEK",
                "values": [0.54, 0.432]
              }
            ]
          },
          {
            "name": "Abonnemangsavgift",
            "start_time": "2026-01-01T00:00:00+01:00",
            "end_time": "2026-01-01T00:30:00+01:00",
            "time_series": [
              {
                "name": "cost",
                "resolution": "monthly",
                "unit": "SEK",
                "values": [187.5]
              }
            ]
          }
        ]
      }
      ```
    </CodeGroup>

    The response breaks down the cost **per component**. Each component returns the final cost time series (pass `?include_intermediate_time_series=true` to also see intermediate steps):

    * **Energiskatt**: 1.5 kWh × 0.36 SEK/kWh = 0.54 SEK, and 1.2 kWh × 0.36 SEK/kWh = 0.432 SEK
    * **Abonnemangsavgift**: Fixed 187.50 SEK/month

    No black boxes — every step is visible.
  </Step>
</Steps>

## What's next

<Columns cols={2}>
  <Card title="Calculation Pipelines" icon="diagram-project" horizontal href="/api-reference/cost-of-energy/calculation-pipeline">
    Understand the expression engine that powers all cost calculations
  </Card>

  <Card title="In Optimisation" icon="bullseye" horizontal href="/api-reference/cost-of-energy/optimisation">
    Use the same pipelines to build optimisation models
  </Card>

  <Card title="API Reference" icon="code" horizontal href="/api-reference/cost-of-energy/overview">
    Full reference for tariffs, components, functions, and endpoints
  </Card>

  <Card title="MCP Integration" icon="sparkles" horizontal href="/guides/mcp">
    Connect your AI tools directly to the Cost of Energy API
  </Card>

  <Card title="Authentication" icon="key" horizontal href="/guides/authentication">
    API key management and security best practices
  </Card>
</Columns>