JouloDocs
Api referenceEnergy

Get what charging cost, and the cost per kilometre

What your charging cost over a period, per session from the EPEX price of each moment: on a dynamic contract with your supplier, on your own fixed tariff (only when you entered one and your contract is not dynamic), and with smart charging. The same sums as the cost card in the dashboard. priced_share below 1 means part of the kWh had no price, so the costs are a lower bound. ere.value_eur is the indicative ERE value of the kWh on stations that count. session_list holds the newest 100 sessions; the totals cover all of them. per_km is what a kilometre cost over the same period: (power per kWh minus net ERE per kWh) times the consumption of your car. It counts only sessions with a price for their whole duration (sessions_without_price says how many fell out), so per_km.kwh can be lower than kwh. cents_per_km is after the ERE and cents_per_km_without_ere before it, both rounded to one decimal; both are null when fewer than min_kwh kWh had a price. ere_net_eur_per_kwh is the net ERE per kWh the block takes off. With ere_basis own_position it is your own average this year, the figure the dashboard uses: ERE already sold at their sale price, the rest at the indicative price. That needs the position:read scope. Without it, or without a position, ere_basis is indicative: the indicative price after your fee. It can differ from ere.net_eur_per_kwh, which is always the indicative price. power_price says what the power was priced at: dynamic, own_fixed_tariff, or default_fixed_tariff (Joulo's default tariff, because you entered none). consumption is an assumption, not a measurement: the WLTP median of your model at the RDW (source model, with car), of your brand (brand), or of every model when you chose no car (fleet). Consumption on the road is usually higher. petrol is the reference: euro 95 at the average Dutch pump price (CBS) and litres_per_100km. km is the kilometres per_km.kwh adds at that consumption. Charging away from home is not in the figure. Default period: the last 30 days, at most 366 days. Requires the profile:read scope.

GET
/costs
AuthorizationBearer <token>

API token from the Joulo dashboard, or an OAuth2 access token.

In: header

Query Parameters

from?string

A date (start of that day in Amsterdam) or an ISO date-time.

to?string

A date (end of that day in Amsterdam) or an ISO date-time.

Response Body

curl -X GET "https://api.joulo.nl/functions/v1/api/costs?from=2026-09-01&to=2026-09-30"
{
  "from": "2026-08-31T22:00:00.000Z",
  "to": "2026-09-30T22:00:00.000Z",
  "contract": {
    "type": "dynamic",
    "supplier": "Tibber",
    "own_fixed_eur_per_kwh": null
  },
  "sessions": 38,
  "kwh": 350.7,
  "priced_share": 0.902,
  "dynamic_cost_eur": 109.07,
  "dynamic_avg_eur_per_kwh": 0.311,
  "fixed_cost_eur": null,
  "smart": {
    "sessions": 34,
    "dynamic_cost_eur": 99.22,
    "smart_cost_eur": 91.86,
    "saving_eur": 7.36
  },
  "your_cost_eur": 109.07,
  "ere": {
    "eligible_kwh": 350.7,
    "net_eur_per_kwh": 0.1093,
    "value_eur": 38.33,
    "indicative": true
  },
  "your_cost_after_ere_eur": 70.74,
  "per_km": {
    "cents_per_km": 2.5,
    "cents_per_km_without_ere": 4.1,
    "kwh": 316.4,
    "km": 2415,
    "min_kwh": 5,
    "sessions_without_price": 4,
    "power_price": "dynamic",
    "power_eur_per_kwh": 0.3136,
    "ere_net_eur_per_kwh": 0.1214,
    "ere_basis": "own_position",
    "consumption": {
      "kwh_per_100km": 13.1,
      "source": "model",
      "car": "Tesla Model Y",
      "basis": "wltp",
      "measured_on": "2026-11-07"
    },
    "petrol": {
      "cents_per_km": 13.7,
      "eur_per_litre": 2.284,
      "litres_per_100km": 6,
      "measured_on": "2026-11-02",
      "source": "CBS 80416ned"
    },
    "home_charging_only": true
  },
  "session_list": [
    {
      "session_id": "f61a024a-8b12-438f-bc09-ef7cb9940c0c",
      "charger_id": "de01f434-60b4-4ea6-96c6-b16020c51a16",
      "started_at": "2026-09-30T18:24:42+00:00",
      "ended_at": "2026-10-01T06:39:44+00:00",
      "kwh": 14.4,
      "dynamic_cost_eur": 5.26,
      "smart_cost_eur": 5.1,
      "fixed_cost_eur": null,
      "priced_share": 1,
      "counts_for_ere": true
    }
  ],
  "session_list_truncated": false
}
{
  "error": "connection_type is required and must be \"ocpp\""
}
{
  "error": "Missing or invalid API token"
}
{
  "error": "Insufficient scope",
  "required_scope": "chargers:read"
}