Skip to main content

Delta queries (since / If-Modified-Since)

The /api/v1/tariffs, /api/v1/tariffs/components, and /api/v1/prices endpoints support filtering by last-modified time — useful if you're building a client that polls SENS on a schedule instead of fetching the entire dataset every time.

Why it matters​

Without delta filtering, every poll pulls the full catalog (hundreds of tariffs), even if nothing changed since the last request. That wastes bandwidth, CPU time on both sides, and — for LLM/agent-based clients — context tokens. since lets you ask only for what changed.

The since query parameter​

An ISO-8601 (UTC) timestamp or a bare date:

curl -s "https://api.getsens.energy/api/v1/tariffs?since=2026-08-20T12:00:00Z" \
  -H "X-API-KEY: $SENS_API_KEY"

# or a bare date (interpreted as start of day UTC)
curl -s "https://api.getsens.energy/api/v1/tariffs?since=2026-08-20" \
  -H "X-API-KEY: $SENS_API_KEY"

If nothing changed since the given timestamp, the response is 200 OK with an empty list ("data": []).

The If-Modified-Since header​

The standard conditional HTTP header — enables classic caching behavior instead of manually tracking a timestamp:

curl -s "https://api.getsens.energy/api/v1/tariffs" \
  -H "X-API-KEY: $SENS_API_KEY" \
  -H "If-Modified-Since: Thu, 20 Aug 2026 12:00:00 GMT"

If nothing changed, the API returns 304 Not Modified (no body) — instead of an empty JSON list, as with since. Every response also carries a Last-Modified header, which you can store and pass back on the next request.

Invalid format​

A malformed since value returns 400 Bad Request:

{
  "error": "invalid_parameter",
  "message": "Invalid 'since' timestamp format. Expected ISO-8601 (e.g. 2026-08-20T12:00:00Z) or YYYY-MM-DD."
}

Source of the timestamp​

The updated_at field in the response (for /prices — meta.last_updated_at) is the authoritative last-modified marker for a record — filter/compare against it, not against when you fetched the data.

See also​