Tibber History API

openapi: 3.2.0
info:
  title: Tibber Data History API
  description: Tibber's modern OAuth 2.0 REST API exposing third-party connected IoT devices and their historical time series.
  version: v1
  contact:
    name: Tibber Data API
    url: https://data-api.tibber.com/docs/
servers:
- url: https://data-api.tibber.com
  description: Tibber Data API (production)
security:
- oauth2: []
tags:
- name: History
  description: Historical time series at quarter-hour, hourly, daily, and monthly resolution.
paths:
  /v1/homes/{homeId}/devices/{deviceId}/history:
    get:
      tags:
      - History
      summary: Get Device History
      operationId: getDeviceHistory
      description: Paginated, immutable historical time series for the device at the chosen resolution. Use `since` and `until` to bound the window and walk forward or backward; the API clamps the window to its retention policy and truncates minutes, seconds, and milliseconds. Follow the `next` and `prev` cursor links rather than picking arbitrary page sizes.
      parameters:
      - in: path
        name: homeId
        required: true
        schema:
          type: string
          format: uuid
      - in: path
        name: deviceId
        required: true
        schema:
          type: string
      - in: query
        name: resolution
        required: true
        schema:
          type: string
          enum:
          - quarterHour
          - hour
          - day
          - month
      - in: query
        name: since
        schema:
          type: string
          format: date-time
        description: Inclusive lower bound, used for forward pagination.
      - in: query
        name: until
        schema:
          type: string
          format: date-time
        description: Inclusive upper bound, used for backward pagination.
      responses:
        '200':
          description: A page of device history points.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceHistoryPage'
        '404':
          description: Device not found.
        '429':
          description: Rate limit exceeded.
components:
  schemas:
    DeviceHistoryPage:
      type: object
      properties:
        query:
          type: object
          properties:
            effectiveStart:
              type: string
              format: date-time
            effectiveEnd:
              type: string
              format: date-time
            resolution:
              type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/DeviceHistoryPoint'
        next:
          type: string
          format: uri
        prev:
          type: string
          format: uri
    DeviceHistoryPoint:
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        metrics:
          type: object
          additionalProperties:
            type: number
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 Authorization Code Flow with optional PKCE.
      flows:
        authorizationCode:
          authorizationUrl: https://thewall.tibber.com/connect/authorize
          tokenUrl: https://thewall.tibber.com/connect/token
          refreshUrl: https://thewall.tibber.com/connect/token
          scopes:
            openid: OpenID identity.
            profile: User profile.
            email: User email.
            offline_access: Issue refresh tokens.
            data-api-user-read: Basic user context (required baseline).
            data-api-homes-read: List the user's homes.
            data-api-vehicles-read: Read connected electric vehicles.
            data-api-chargers-read: Read EV chargers and EVSE equipment.
            data-api-thermostats-read: Read thermostats, heat pumps, and space heaters.
            data-api-energy-systems-read: Read home batteries and hybrid systems.
            data-api-inverters-read: Read solar inverters.