Skip to main content

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.

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.
AI-assisted developmentThe Cost of Energy API is designed to work with AI tools. Two ways to get started:

MCP Integration

Connect Claude, Cursor, or VS Code directly to the API

llms.txt

Give your AI tool full API context in one file

​
Prerequisites

You need an API key. Sign up at console.engrate.io and generate one.
1

Find a system operator

Look up Swedish DSOs (system operators) using the Core API. Here we search by name:
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"
Copy the id — you’ll use it to find tariffs in the next step.
2

List tariffs for the operator

Fetch tariffs offered by that system operator:
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"
Each tariff has a name, summary, eligibility criteria, and a list of tariff_components. Copy the id of the tariff you want to inspect.
3

Fetch the full tariff

Get the complete tariff with all its calculation pipelines:
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"
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 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).
4

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:
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]
      }
    ]
  }'
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.

​
What’s next

Calculation Pipelines

Understand the expression engine that powers all cost calculations

In Optimisation

Use the same pipelines to build optimisation models

API Reference

Full reference for tariffs, components, functions, and endpoints

MCP Integration

Connect your AI tools directly to the Cost of Energy API

Authentication

API key management and security best practices