> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minstroem.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get consumption

> Get electricity consumption. Hourly requests cover up to 366 days; daily, monthly, or yearly requests cover up to five years. Limits apply after range normalization.

```http theme={null}
GET /consumer/v1/me/addresses/{addressId}/consumption?from={from}&to={to}&aggregation={aggregation}
```

Follow [Quick start](/consumer-api/quickstart) to try the curl example. See [Time and ranges](/consumer-api/time-and-ranges) and [Data interpretation](/consumer-api/data-interpretation) for help using the results.


## OpenAPI

````yaml GET /me/addresses/{addressId}/consumption
openapi: 3.1.0
info:
  title: Min Strøm Consumer API
  version: 1.0.0
  summary: Read-only access to your own energy data with Min Strøm Plus.
  description: >-
    Read your energy data with an API key created in the iOS app. An active Min
    Strøm Plus subscription is required. See the guides for time ranges, data
    interpretation, and request limits.
  contact:
    name: Min Strøm
    email: engberg@minstroem.app
servers:
  - url: https://api.minstroem.app/consumer/v1
    description: Consumer API
security:
  - ConsumerBearer: []
tags:
  - name: Addresses
    description: Your addresses and available data.
  - name: Energy
    description: Consumption, export and calculated amounts.
  - name: Prices
    description: Confirmed and forecast address prices.
paths:
  /me/addresses/{addressId}/consumption:
    get:
      tags:
        - Energy
      summary: Get consumption
      description: >-
        Get electricity consumption. Hourly requests cover up to 366 days;
        daily, monthly, or yearly requests cover up to five years. Limits apply
        after range normalization.
      operationId: consumption
      parameters:
        - $ref: '#/components/parameters/AddressId'
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - $ref: '#/components/parameters/Aggregation'
      responses:
        '200':
          description: >-
            Available readings in time order. Results may contain gaps or be
            empty.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/LimitMinute'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/RemainingMinute'
            X-RateLimit-Reset-Minute:
              $ref: '#/components/headers/ResetMinute'
            X-RateLimit-Limit-Day:
              $ref: '#/components/headers/LimitDay'
            X-RateLimit-Remaining-Day:
              $ref: '#/components/headers/RemainingDay'
            X-RateLimit-Reset-Day:
              $ref: '#/components/headers/ResetDay'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
              examples:
                synthetic:
                  summary: Synthetic example; not customer data
                  value:
                    addressId: 2b4bf7a8-b5d0-45ab-8d42-3a5688bba167
                    from: '2026-09-05T10:00:00Z'
                    to: '2026-09-05T11:00:00Z'
                    aggregation: hour
                    timeZone: Europe/Copenhagen
                    data:
                      - start: '2026-09-05T10:00:00Z'
                        end: '2026-09-05T11:00:00Z'
                        energyKWh: 2
                        isEstimate: false
                empty:
                  summary: No available rows
                  value:
                    addressId: 2b4bf7a8-b5d0-45ab-8d42-3a5688bba167
                    from: '2026-09-05T10:00:00Z'
                    to: '2026-09-05T11:00:00Z'
                    aggregation: hour
                    timeZone: Europe/Copenhagen
                    data: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnavailableFeature'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/UpstreamUnavailable'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      x-codeSamples:
        - lang: curl
          label: curl
          source: |-
            curl --fail-with-body --silent --show-error --get \
              --header "Authorization: Bearer ${MINSTROEM_API_TOKEN}" \
              --data-urlencode "from=2026-09-05T10:00:00Z" \
              --data-urlencode "to=2026-09-05T11:00:00Z" \
              --data-urlencode "aggregation=hour" \
              "https://api.minstroem.app/consumer/v1/me/addresses/${MINSTROEM_ADDRESS_ID}/consumption"
components:
  parameters:
    AddressId:
      name: addressId
      in: path
      required: true
      description: Address ID returned by List addresses.
      schema:
        type: string
        format: uuid
      example: 2b4bf7a8-b5d0-45ab-8d42-3a5688bba167
    From:
      name: from
      in: query
      required: true
      description: >-
        Inclusive RFC 3339 start with Z or numeric offset. Fractions accepted.
        Expanded outward to the interval.
      schema:
        $ref: '#/components/schemas/Timestamp'
      example: '2026-09-05T10:00:00Z'
    To:
      name: to
      in: query
      required: true
      description: >-
        Exclusive RFC 3339 end after from. Expands outward unless aligned. Caps
        apply after expansion.
      schema:
        $ref: '#/components/schemas/Timestamp'
      example: '2026-09-05T11:00:00Z'
    Aggregation:
      name: aggregation
      in: query
      required: true
      description: Time interval for grouping readings.
      schema:
        $ref: '#/components/schemas/Aggregation'
      example: hour
  headers:
    RequestId:
      description: Response UUID for support. Never send your key.
      schema:
        type: string
        format: uuid
    CacheControl:
      description: Private, non-cacheable response.
      schema:
        type: string
        const: private, no-store
    LimitMinute:
      description: Configured minute limit; present after quota evaluation.
      schema:
        type: integer
        minimum: 1
      example: 60
    RemainingMinute:
      description: Remaining minute attempts; present after quota evaluation.
      schema:
        type: integer
        minimum: 0
    ResetMinute:
      description: >-
        Minute reset as Unix seconds (UTC fixed window); present after quota
        evaluation.
      schema:
        type: integer
        format: int64
    LimitDay:
      description: Configured day limit; present after quota evaluation.
      schema:
        type: integer
        minimum: 1
      example: 2000
    RemainingDay:
      description: Remaining day attempts; present after quota evaluation.
      schema:
        type: integer
        minimum: 0
    ResetDay:
      description: >-
        Day reset as Unix seconds (UTC fixed window); present after quota
        evaluation.
      schema:
        type: integer
        format: int64
    RetryAfter:
      description: Seconds until the latest reset among exhausted windows; present on 429.
      schema:
        type: integer
        minimum: 1
  schemas:
    UsageResponse:
      type: object
      additionalProperties: false
      required:
        - addressId
        - from
        - to
        - aggregation
        - timeZone
        - data
      properties:
        addressId:
          type: string
          format: uuid
        from:
          $ref: '#/components/schemas/Timestamp'
        to:
          $ref: '#/components/schemas/Timestamp'
        aggregation:
          $ref: '#/components/schemas/Aggregation'
        timeZone:
          $ref: '#/components/schemas/TimeZone'
        data:
          type: array
          items:
            $ref: '#/components/schemas/UsageInterval'
          description: Ascending sparse rows; empty is valid. Gaps are not zero readings.
    Timestamp:
      type: string
      format: date-time
      description: UTC instant encoded with Z. Interval ends are exclusive.
      examples:
        - '2026-09-05T10:00:00Z'
    Aggregation:
      type: string
      enum:
        - hour
        - day
        - month
        - year
    TimeZone:
      type: string
      description: >-
        Calendar used for interval boundaries: Europe/Copenhagen. Timestamps are
        UTC.
      examples:
        - Europe/Copenhagen
    UsageInterval:
      type: object
      additionalProperties: false
      required:
        - start
        - end
        - energyKWh
        - isEstimate
      properties:
        start:
          $ref: '#/components/schemas/Timestamp'
        end:
          $ref: '#/components/schemas/Timestamp'
        energyKWh:
          type: number
          format: double
          description: Returned energy in kWh. Missing rows are not zero.
        isEstimate:
          type: boolean
          description: True when the reading is estimated.
    Error:
      type: object
      additionalProperties: false
      required:
        - error
        - reason
        - errorCode
      properties:
        error:
          type: boolean
          const: true
        reason:
          type: string
          description: Safe human-readable explanation; use errorCode for program logic.
        errorCode:
          type: string
          description: Stable machine-readable error code.
  responses:
    BadRequest:
      description: >-
        Check the parameters and requested range: invalid_parameter,
        invalid_range, or range_too_large.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: A request parameter is invalid.
            errorCode: invalid_parameter
    Unauthorized:
      description: The API key is invalid (invalid_token) or expired (credential_expired).
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: A valid credential is required.
            errorCode: invalid_token
    Forbidden:
      description: >-
        An active Plus subscription is required (plus_required), or access is
        denied (forbidden).
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: An active Min Strøm Plus subscription is required.
            errorCode: plus_required
    NotFound:
      description: The address could not be found. Use an ID returned by List addresses.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: The resource was not found.
            errorCode: resource_not_found
    UnavailableFeature:
      description: This data is unavailable for the address. Check its capability flags.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: This feature is unavailable for this address.
            errorCode: feature_unavailable
    RateLimited:
      description: >-
        Minute or daily quota exhausted. Denied attempts count too; honor
        Retry-After.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: The request limit has been exceeded.
            errorCode: rate_limited
    InternalError:
      description: An unexpected error occurred. Retry later or contact support.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: An unexpected error occurred.
            errorCode: internal_error
    UpstreamUnavailable:
      description: Data is temporarily unavailable. Retry later.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: The data provider is temporarily unavailable.
            errorCode: upstream_unavailable
    ServiceUnavailable:
      description: >-
        Subscription verification or request limiting is temporarily
        unavailable. Retry later.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit-Minute:
          $ref: '#/components/headers/LimitMinute'
        X-RateLimit-Remaining-Minute:
          $ref: '#/components/headers/RemainingMinute'
        X-RateLimit-Reset-Minute:
          $ref: '#/components/headers/ResetMinute'
        X-RateLimit-Limit-Day:
          $ref: '#/components/headers/LimitDay'
        X-RateLimit-Remaining-Day:
          $ref: '#/components/headers/RemainingDay'
        X-RateLimit-Reset-Day:
          $ref: '#/components/headers/ResetDay'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: true
            reason: Min Strøm Plus subscription verification is unavailable.
            errorCode: entitlement_unavailable
  securitySchemes:
    ConsumerBearer:
      type: http
      scheme: bearer
      description: >-
        API key created in the iOS app. Requires an active Min Strøm Plus
        subscription.

````