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

# Instantly calculate energy cost

> Ingests a meter record and instantly returns the import or export monetary value (cost) of energy.

- If you are metering a device, submit records using `device_id` parameter.
- If you are metering a location (i.e. main supply address meter), submit records under `location_id` parameter.

<Info>Meter records that are submitted via this endpoint will be permanently stored and will be used for other cost-calculations endpoints.</Info>



## OpenAPI

````yaml api-reference/anode/flatpeak-api-spec-anode.json POST /costs/instant
openapi: 3.0.3
info:
  description: Flatpeak API
  version: 2025-09-14.anode
  title: Flatpeak API
  termsOfService: https://flatpeak.com/legal
  contact:
    name: Technical Support
    email: support@flatpeak.com
    url: https://flatpeak.com/contact
  license:
    name: Apache 2.0
    url: https://flatpeak.com/legal
servers:
  - url: https://api.flatpeak.com
    description: Location
security: []
tags:
  - name: Consumption
    description: Consumption operations
  - name: Customers
    description: Customer operations
  - name: Devices
    description: Device operations
  - name: Meters
    description: Meter readings operations
  - name: Events
    description: Events operations
  - name: Login
    description: Bearer auth token operations
  - name: Connect
    description: Connect operations
  - name: Locations
    description: Location operations
  - name: Rates
    description: Rates operations
  - name: Costs
    description: Consumption cost calculations
  - name: Schedules
    description: Consumption schedules
  - name: Tariffs
    description: Tariff operations
  - name: Slots
    description: Slots operations
externalDocs:
  description: Location documentation
  url: https://docs.flatpeak.com
paths:
  /costs/instant:
    parameters: []
    post:
      tags:
        - Costs
      summary: Instantly calculate energy cost
      description: >-
        Ingests a meter record and instantly returns the import or export
        monetary value (cost) of energy.


        - If you are metering a device, submit records using `device_id`
        parameter.

        - If you are metering a location (i.e. main supply address meter),
        submit records under `location_id` parameter.


        <Info>Meter records that are submitted via this endpoint will be
        permanently stored and will be used for other cost-calculations
        endpoints.</Info>
      operationId: get-cost-instant
      parameters:
        - schema:
            type: boolean
          in: query
          name: non_persistent
          description: >-
            Set to `true` to avoid storing metering records permanently. Use for
            simulating consumption to estimate potential energy costs.
      requestBody:
        $ref: '#/components/requestBodies/MeterRecordSubmit'
      responses:
        '200':
          $ref: '#/components/responses/MeterRecord'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
        '429':
          $ref: '#/components/responses/429'
      security:
        - bearerAuth: []
components:
  requestBodies:
    MeterRecordSubmit:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MeterRecordSubmit'
  responses:
    '403':
      description: 403 forbidden
      content:
        application/json:
          schema:
            type: object
            x-examples:
              Example:
                message: Bad credentials
            properties:
              object:
                type: string
                example: error
                x-stoplight:
                  id: gria4ysjd9zhk
                default: error
              type:
                type: string
                x-stoplight:
                  id: 7mhtfljidnqcu
                example: invalid_request
                default: invalid_request
              code:
                type: string
                x-stoplight:
                  id: sy7ljpdy5wdes
                example: access_denied
                default: access_denied
              time_created:
                type: string
                x-stoplight:
                  id: 84d5biv9dfbc9
                format: date-time
                example: '2025-01-01T00:00:00Z'
            required:
              - object
              - type
              - code
          examples: {}
    '422':
      description: 422 Data not available
      content:
        application/json:
          schema:
            type: object
            x-examples:
              Example:
                object: error
                type: api_error
                live_mode: false
                time_created: '2022-01-24T14:15:22.003'
                code: country_code_missing
                message: Country code is required
            properties:
              object:
                type: string
                x-stoplight:
                  id: 8tu6jw6w7a4ds
                default: error
                example: error
              type:
                type: string
                x-stoplight:
                  id: pi73vu0gm23xz
                example: invalid_request
                default: invalid_request
              context:
                type: string
                x-stoplight:
                  id: 86mrnnt9y68p9
                example: api.price_get
              code:
                type: string
                x-stoplight:
                  id: yvmrv5mczcj3f
                example: no_tariff_connected
              message:
                type: string
                x-stoplight:
                  id: n8zx3cn5xogky
                example: No tariff connected for IMPORT direction
              time_created:
                type: string
                x-stoplight:
                  id: wffseagefabdy
                format: date-time
                example: '2025-01-01T00:00:00Z'
            required:
              - object
              - type
              - context
              - code
              - message
              - time_created
    '429':
      description: 429 Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              object:
                type: string
                x-stoplight:
                  id: irkmp11gg6sjx
                example: error
                default: error
              type:
                type: string
                x-stoplight:
                  id: u0gq12cizam3d
                default: rate_limit
                example: rate_limit
              code:
                type: string
                x-stoplight:
                  id: uh7x9404d4w3q
                default: too_many_requests
                example: too_many_requests
              message:
                type: string
                x-stoplight:
                  id: 9z8h79l1coblc
                default: Too many requests. Please retry after a short delay.
                example: Too many requests. Please retry after a short delay.
              time_created:
                type: string
                x-stoplight:
                  id: ea7o3uvdojrtc
                format: date-time
                default: '2026-01-29T17:11:52Z'
                example: '2026-01-29T17:11:52Z'
            required:
              - object
              - type
              - code
              - message
    MeterRecord:
      description: Response example
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MeterRecordResponse'
  schemas:
    MeterRecordSubmit:
      type: object
      x-stoplight:
        id: ggohkmqooylpl
      x-examples: {}
      title: Metering Record Request
      properties:
        location_id:
          type: string
          example: loc_641b90b758fb8e6293716e40
          description: Flatpeak `location_id` that you are submitting metering records for.
          x-stoplight:
            id: 2bm76gqje3md9
        device_id:
          type: string
          example: dev_65e6d8334c8d715963d99db3
          description: >-
            Flatpeak `device_id` you are submitting metering records for. If you
            provided both `location_id` and `device_id`, your records will be
            attributed to `device_id`.
          x-stoplight:
            id: bfmf0zbkzkerf
        session_reference_id:
          type: string
          example: SESSION1234567890
          description: >-
            A reference for a group of metering records, for example, a charging
            session ID.
          x-stoplight:
            id: 5y5sztjasnwz9
        record_reference_id:
          type: string
          example: MET1234567890
          description: A reference for this metering record, for example, meter log ID.
          x-stoplight:
            id: 84jizggwu276k
        energy_flow_direction:
          type: string
          example: INBOUND
          x-stoplight:
            id: sa3mw8pvfzn4h
          description: >-
            Energy flow direction. Set to `INBOUND` or `OUTBOUND`. Defaults to
            `INBOUND`.
        tariff_direction:
          type: string
          example: IMPORT
          x-stoplight:
            id: sa3mw8pvfzn4h
          description: >-
            Tariff direction to apply. Set to `IMPORT`, `EXPORT`, or `LOCAL`.
            Defaults to `IMPORT`.
        units:
          type: string
          example: W
          description: >-
            Units of measure, supported values are W, KW, WH, KWH. When W or KW
            units are submitted, cost will be calculated using the constant
            power rate over the period.
        confidence:
          type: number
          example: 1
          description: >-
            Estimated confidence of data where '1' is 100% accurate and 0.1 is
            10% accurate. Defaults to '1'. *This parameter is in beta. Contact
            support to enable*.
          x-stoplight:
            id: 2zl60dheu7apt
        value:
          type: number
          example: 20567
          description: Amount of energy measured.
        start_time:
          type: string
          example: '2022-02-01T10:30:00Z'
          description: >-
            Metering record start time. In RFC3339 format, e.g.
            `2023-06-15T09:00:00Z` or with time-offset, e.g.
            `2023-06-15T08:00:00+01:00`.
          format: date-time
        end_time:
          type: string
          example: '2022-02-01T11:00:00Z'
          description: >-
            Metering record end time. In RFC3339 format, e.g.
            `2023-06-15T09:00:00Z` or with time-offset, e.g.
            `2023-06-15T08:00:00+01:00`.
          format: date-time
      required:
        - location_id
        - units
        - value
        - start_time
        - end_time
    MeterRecordResponse:
      type: object
      x-stoplight:
        id: 5ngy06j5ketq3
      x-examples: {}
      properties:
        id:
          type: string
          example: mre_65e641b570b2901d3a40199d
          description: Flatpeak meter record id.
        object:
          type: string
          description: Flatpeak object type, i.e. `meter_record`.
          example: meter_record
        live_mode:
          type: boolean
          x-stoplight:
            id: 0ftef6ayhczsc
          description: >-
            Has the value true if the object exists in live mode or the value
            false if the object exists in test mode.
        energy_flow_direction:
          type: string
          x-stoplight:
            id: ujr13o7jve38m
          example: INBOUND
          description: >-
            Energy flow direction. Set to `INBOUND` or `OUTBOUND`. Defaults to
            `INBOUND`.
        tariff_direction:
          type: string
          x-stoplight:
            id: ujr13o7jve38m
          example: IMPORT
          description: >-
            Specified tariff direction. Possible values are `IMPORT`, `EXPORT`
            or `LOCAL`.
        currency_code:
          type: string
          x-stoplight:
            id: tl558twl7se1k
          description: Currency code for cost of energy measure.
          example: GBP
        energy_units:
          type: string
          x-stoplight:
            id: 2b8wc37xrt1h1
          description: Units of energy measure.
          example: WH
        request:
          $ref: '#/components/schemas/MeterRecordSubmitRecord'
        data:
          $ref: '#/components/schemas/EnergyCostResponse'
        time_created:
          type: string
          description: Time when this object was created. In UTC.
          example: '2022-02-01T10:33:00Z'
        account_id:
          type: string
          x-stoplight:
            id: lwpqgdf9z1zmv
          description: Flatpeak account ID.
          example: acc_661677911f2197045e6cf1b1
      required:
        - id
        - object
        - live_mode
        - energy_flow_direction
        - tariff_direction
        - currency_code
        - energy_units
        - request
        - data
        - time_created
    MeterRecordSubmitRecord:
      type: object
      x-stoplight:
        id: 19zj1xxxfn6s1
      x-examples: {}
      title: Metering Record Request
      properties:
        location_id:
          type: string
          example: loc_641b90b758fb8e6293716e40
          description: Flatpeak `location_id` that you are submitting metering records for.
          x-stoplight:
            id: 2bm76gqje3md9
        device_id:
          type: string
          example: dev_65e6d8334c8d715963d99db3
          description: >-
            Flatpeak `device_id` you are submitting metering records for. If you
            provided both `location_id` and `device_id` your records will be
            attributed to `device_id`.
          x-stoplight:
            id: bfmf0zbkzkerf
        session_reference_id:
          type: string
          example: SESSION1234567890
          description: >-
            A reference for a group of metering records, for example, a charging
            session ID.
          x-stoplight:
            id: 5y5sztjasnwz9
        record_reference_id:
          type: string
          example: MET1234567890
          description: A reference for this metering record, for example, meter log ID.
          x-stoplight:
            id: 84jizggwu276k
        energy_flow_direction:
          type: string
          example: IMPORT
          x-stoplight:
            id: sa3mw8pvfzn4h
          description: >-
            Energy flow direction. Set to `INBOUND` or `OUTBOUND`. Defaults to
            `INBOUND`.
        tariff_direction:
          type: string
          example: IMPORT
          x-stoplight:
            id: sa3mw8pvfzn4h
          description: >-
            Indicates the tariff direction; possible values are `IMPORT`,
            `EXPORT`, or `LOCAL`.
        units:
          type: string
          example: W
          description: >-
            Units of measure, supported values are W, KW, WH, KWH. When W or KW
            units are submitted, cost will be calculated using the constant
            power rate over the period.
        confidence:
          type: number
          example: 1
          description: >-
            Estimated confidence of data where '1' is 100% accurate and 0.1 is
            10% accurate. Defaults to '1'. *This parameter is in beta. Contact
            support to enable*.
          x-stoplight:
            id: 2zl60dheu7apt
        value:
          type: number
          example: 20567
          description: Amount of energy measured.
        start_time:
          type: string
          example: '2022-02-01T10:30:00Z'
          description: >-
            Metering record start time. In RFC3339 format, e.g.
            `2023-06-15T09:00:00Z` or with time-offset, e.g.
            `2023-06-15T08:00:00+01:00`.
        end_time:
          type: string
          example: '2022-02-01T11:00:00Z'
          description: >-
            Metering record end time. In RFC3339 format, e.g.
            `2023-06-15T09:00:00Z` or with time-offset, e.g.
            `2023-06-15T08:00:00+01:00`.
        non_persistent:
          type: boolean
          x-stoplight:
            id: rrpodpt33echq
          description: When set to `true`, metering records are not stored permanently.
          default: false
      required:
        - location_id
        - units
        - value
        - start_time
        - end_time
    EnergyCostResponse:
      type: object
      x-stoplight:
        id: 99p27zfb4qlf6
      x-examples: {}
      description: Value of energy object
      properties:
        start_time:
          type: string
          description: Start of time period, in timezone of the original request.
          format: date-time
          example: '2022-02-01T10:30:00Z'
        end_time:
          type: string
          description: End of time period, in timezone of the original request.
          format: date-time
          example: '2022-02-01T11:00:00Z'
        session_reference_id:
          type: string
          description: >-
            `session_reference_id` from meter record as submitted by you via
            `/meters` endpoints. Only returned if request made by this ID.
          example: SESSION1234567890
          x-stoplight:
            id: l7adep1lntbfu
        record_reference_id:
          type: string
          description: >-
            `record_reference_id` from meter record as submitted by you via
            `/meters` endpoints. Only returned if request made by this ID.
          example: MET1234567890
          x-stoplight:
            id: esh6jcj0khg2k
        energy:
          type: object
          x-stoplight:
            id: dr4p3n0fjgp4i
          description: Amount of energy.
          required:
            - value
          properties:
            value:
              type: integer
              x-stoplight:
                id: znh1bc9pnkd7q
              description: Amount of energy in `energy_units`.
              example: 10284
        cost:
          type: object
          description: Monetary cost of energy.
          required:
            - value
            - confidence
          x-stoplight:
            id: 7n87mnzt4j4g9
          properties:
            value:
              type: number
              description: Monetary value in *large* currency units.
              x-stoplight:
                id: aey0ddmwfhp7b
              example: 928.372
            confidence:
              type: number
              description: >-
                Estimated confidence of data where '1' is 100% accurate and 0.1
                is 10% accurate.
              example: 1
      required:
        - start_time
        - end_time
        - energy
        - cost
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate with `bearer` you obtained from
        [authentication](/api-reference/anode/authentication) endpoint.

````