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

# Retrieve attributed usage

> This endpoint retrieves the usage of an active subscription per value of a governance entity, with optional filters, a custom time range and one charge split by its filters.



## OpenAPI

````yaml GET /customers/{external_customer_id}/attributed_usage
openapi: 3.1.0
info:
  title: Lago API documentation
  description: >-
    Lago API allows your application to push customer information and metrics
    (events) from your application to the billing application.
  version: 1.57.0
  license:
    name: AGPLv3
    url: https://github.com/getlago/lago-openapi/blob/main/LICENSE
  contact:
    email: tech@getlago.com
servers:
  - url: https://api.getlago.com/api/v1
    description: US Lago cluster
  - url: https://api.eu.getlago.com/api/v1
    description: EU Lago cluster
security:
  - bearerAuth: []
tags:
  - name: activity_logs
    description: Everything about Activity logs
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/audit-logs/activity-logs-object
  - name: analytics
    description: Everything about Analytics
  - name: api_logs
    description: Everything about API logs
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/audit-logs/api-logs-object
  - name: billable_metrics
    description: Everything about Billable metric collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/billable-metrics/object
  - name: features
    description: Everything about Feature collection
    externalDocs:
      description: Find out more
      url: >-
        https://getlago.com/docs/api-reference/entitlements/features/feature-object
  - name: entitlements
    description: Everything about Entitlement collection
    externalDocs:
      description: Find out more
      url: >-
        https://getlago.com/docs/api-reference/entitlements/plan-entitlements/plan-entitlement-object
  - name: billing_entities
    description: Everything about Billing Entities
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/billing-entities/object
  - name: customers
    description: Everything about Customer collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/customers/object
  - name: plans
    description: Everything about Plan collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/plans/object
  - name: subscriptions
    description: Everything about Subscription collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/subscriptions/subscription-object
  - name: events
    description: Everything about Event collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/events/event-object
  - name: organizations
    description: Everything about Organization collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/organizations/organization-object
  - name: taxes
    description: Everything about Tax collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/taxes/tax-object
  - name: coupons
    description: Everything about Coupon collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/coupons/coupon-object
  - name: add_ons
    description: Everything about Add-on collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/add-ons/add-on-object
  - name: fees
    description: Everything about Fees
    externalDocs:
      description: Find out more
      url: >-
        https://getlago.com/docs/api-reference/invoices/invoice-object#fee-object
  - name: invoices
    description: Everything about Invoice collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/invoices/invoice-object
  - name: wallets
    description: Everything about Wallet collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/wallets/wallet-object
  - name: credit_notes
    description: Everything about Credit notes collection
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/credit-notes/credit-note-object
  - name: webhooks
    description: Everything about Webhooks
    externalDocs:
      description: Find out more
      url: >-
        https://getlago.com/docs/api-reference/webhooks/format---signature#1-retrieve-the-public-key
  - name: webhook_endpoints
    description: Everything about Webhook Endpoints
    externalDocs:
      description: Find out more
      url: >-
        https://getlago.com/docs/api-reference/webhook-endpoints/webhook-endpoint-object
  - name: payment_receipts
    description: Everything about Payment receipts
    externalDocs:
      description: Find out more
      url: >-
        https://getlago.com/docs/api-reference/payment-receipts/payment-receipt-object
  - name: payment_requests
    description: Everything about PaymentRequests
    externalDocs:
      description: Find out more
      url: >-
        https://getlago.com/docs/api-reference/payment-requests/payment-request-object
  - name: payments
    description: Everything about Payments
    externalDocs:
      description: Find out more
      url: https://getlago.com/docs/api-reference/payments/payment-object
  - name: payment_methods
    description: Everything about Payment Methods
    externalDocs:
      description: Find out more
      url: >-
        https://getlago.com/docs/api-reference/payment-methods/payment-method-object
  - name: quotes
    description: Everything about Quote collection
  - name: order_forms
    description: Everything about Order form collection
  - name: orders
    description: Everything about Order collection
  - name: usage_attribution_types
    description: Everything about Usage attribution type collection
externalDocs:
  description: Lago Github
  url: https://github.com/getlago
paths:
  /customers/{external_customer_id}/attributed_usage:
    get:
      tags:
        - customers
      summary: Retrieve customer attributed usage
      description: >-
        This endpoint retrieves the usage of an active subscription broken down
        by the values of a usage attribution type, one level of the account tree
        at a time. Only charges whose billable metric uses the `count_agg` or
        `sum_agg` aggregation and is not recurring are included. By default, the
        usage covers the current billing period, narrowed to its last 31 days
        when the period is longer.
      operationId: findCustomerAttributedUsage
      parameters:
        - $ref: '#/components/parameters/external_customer_id_path'
        - name: external_subscription_id
          in: query
          description: >-
            The unique identifier of the subscription within your application.
            The subscription must be active.
          required: true
          explode: true
          schema:
            type: string
            example: sub_1234567890
        - name: group_by
          in: query
          description: >-
            Code of the usage attribution type to group the usage by. When the
            type has a parent, `filters` must include a value of the parent
            type, so the tree is read one level at a time. Lago tracks up to
            100,000 values per type for each customer. Once the type reaches
            this limit, grouping by it returns a `too_many_values` validation
            error, unless `filters` includes a value of its parent type.
          required: true
          explode: true
          schema:
            type: string
            example: team
        - name: filters
          in: query
          description: >-
            Values of usage attribution types to filter the usage by, keyed by
            type code, e.g.
            `filters[department]=rnd&filters[model][]=opus&filters[model][]=haiku`.
            Each type accepts up to 20 values, and up to 3 `flat` types can be
            filtered on. More than 20 values for a type returns a
            `too_many_values` validation error.
          required: false
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
            example:
              department: rnd
        - name: from_datetime
          in: query
          description: >-
            Start of the period, in ISO 8601 format. It must be sent together
            with `to_datetime`, and the period cannot be longer than 31 days. It
            is moved to the start of the subscription when earlier.
          required: false
          explode: true
          schema:
            type: string
            format: date-time
            example: '2022-04-01T00:00:00Z'
        - name: to_datetime
          in: query
          description: >-
            End of the period, in ISO 8601 format. It must be sent together with
            `from_datetime`.
          required: false
          explode: true
          schema:
            type: string
            format: date-time
            example: '2022-04-30T23:59:59Z'
        - name: charge_codes[]
          in: query
          description: >-
            Codes of the charges of the plan to include. All the supported
            charges are included when it is not sent.
          required: false
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - tokens
        - name: split_charge_code
          in: query
          description: >-
            Code of a charge of the plan to split by charge filter, with one
            entry per filter in `charges_usage`. The filters are returned 10 at
            a time, in the order of the charge, starting at
            `split_filters_offset`. The charge must have at least 1 filter, and
            must be part of `charge_codes[]` when it is sent. A
            `too_many_filters` validation error is returned when the filter
            values of the charge are too many to match events.
          required: false
          explode: true
          schema:
            type: string
            example: tokens
        - name: split_filters_offset
          in: query
          description: >-
            Index of the first filter of the split charge to return, starting at
            0. Use it with `split_filters_count` to page through the filters 10
            at a time. It is ignored when `split_charge_code` is not sent.
          required: false
          explode: true
          schema:
            type: integer
            minimum: 0
            maximum: 20000
            default: 0
            example: 10
        - name: search_term
          in: query
          description: >-
            Filter the attribution values by search term, up to 100 characters.
            The totals are not affected by the search.
          required: false
          explode: true
          schema:
            type: string
            maxLength: 100
            example: eng
        - name: basis
          in: query
          description: >-
            Basis of the breakdown. With `units`, no amount is computed and
            values are ranked by units, summed across the selected charges. With
            `amount`, amounts are computed and values are ranked by amount.
          required: false
          explode: true
          schema:
            type: string
            enum:
              - units
              - amount
            default: units
            example: amount
        - $ref: '#/components/parameters/page'
        - name: per_page
          in: query
          description: Number of attribution values per page, between 1 and 100.
          required: false
          explode: true
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            example: 20
      responses:
        '200':
          description: Customer attributed usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributedUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Unprocessable entity error
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ApiErrorUnprocessableEntity'
                  - $ref: '#/components/schemas/ApiErrorAttributedUsageQueryLimit'
components:
  parameters:
    external_customer_id_path:
      name: external_customer_id
      in: path
      description: >-
        The customer external unique identifier (provided by your own
        application)
      required: true
      schema:
        type: string
        example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    page:
      name: page
      in: query
      description: >-
        Page number. Defaults to 1. A value that is not a positive integer, such
        as `0`, returns the first page.
      required: false
      explode: true
      schema:
        type: integer
        example: 1
  schemas:
    AttributedUsage:
      type: object
      required:
        - attributed_usage
        - meta
      properties:
        attributed_usage:
          $ref: '#/components/schemas/AttributedUsageObject'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ApiErrorUnprocessableEntity:
      type: object
      required:
        - status
        - error
        - code
        - error_details
      properties:
        status:
          type: integer
          format: int32
          example: 422
        error:
          type: string
          example: Unprocessable entity
        code:
          type: string
          example: validation_errors
        error_details:
          type: object
    ApiErrorAttributedUsageQueryLimit:
      type: object
      required:
        - status
        - error
        - code
      properties:
        status:
          type: integer
          format: int32
          example: 422
        error:
          type: string
          example: Unprocessable Entity
        code:
          type: string
          enum:
            - too_many_groups
            - query_timeout
            - memory_limit_exceeded
          description: >-
            Reason why the query exceeded its limits. Narrow the period or add
            filters, then retry.
          example: too_many_groups
    AttributedUsageObject:
      type: object
      required:
        - lago_subscription_id
        - external_subscription_id
        - group_by
        - basis
        - from_datetime
        - to_datetime
        - currency
        - split_filters_count
        - rows
        - unattributed
        - totals
      properties:
        lago_subscription_id:
          type: string
          format: uuid
          description: Unique identifier of the subscription, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        external_subscription_id:
          type: string
          description: Unique identifier of the subscription in your application.
          example: sub_1234567890
        group_by:
          type: string
          description: Code of the usage attribution type the usage is grouped by.
          example: team
        basis:
          type: string
          enum:
            - units
            - amount
          description: >-
            Basis of the breakdown. With `units`, amounts are `null` and values
            are ranked by units, summed across the selected charges. With
            `amount`, amounts are computed and values are ranked by amount.
          example: amount
        from_datetime:
          type: string
          format: date-time
          description: Start of the period of the usage, in UTC.
          example: '2022-04-01T00:00:00Z'
        to_datetime:
          type: string
          format: date-time
          description: End of the period of the usage, in UTC.
          example: '2022-04-30T23:59:59Z'
        currency:
          $ref: '#/components/schemas/Currency'
        split_filters_count:
          type:
            - integer
            - 'null'
          description: >-
            Number of filters of the charge split by `split_charge_code`, across
            all pages. Each response returns up to 10 of them, starting at
            `split_filters_offset`. It is `null` when no charge is split.
          example: 42
        rows:
          type: array
          items:
            $ref: '#/components/schemas/AttributedUsageRowObject'
          description: Usage of each attribution value of the page, ordered by rank.
        unattributed:
          allOf:
            - $ref: '#/components/schemas/AttributedUsageTotalsObject'
          description: >-
            Usage of the events that carry no value for the `group_by` usage
            attribution type.
        totals:
          allOf:
            - $ref: '#/components/schemas/AttributedUsageTotalsObject'
          description: >-
            Usage of the whole level, attributed and unattributed, for all
            pages. A `search_term` does not narrow the totals.
    PaginationMeta:
      type: object
      required:
        - current_page
        - total_pages
        - total_count
      properties:
        current_page:
          type: integer
          description: Current page.
          example: 2
        next_page:
          type:
            - integer
            - 'null'
          description: Next page.
          example: 3
        prev_page:
          type:
            - integer
            - 'null'
          description: Previous page.
          example: 1
        total_pages:
          type: integer
          description: Total number of pages.
          example: 4
        total_count:
          type: integer
          description: Total number of records.
          example: 70
    ApiErrorUnauthorized:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: integer
          format: int32
          example: 401
        error:
          type: string
          example: Unauthorized
    ApiErrorForbidden:
      type: object
      required:
        - status
        - error
        - code
      properties:
        status:
          type: integer
          format: int32
          example: 403
        error:
          type: string
          example: Forbidden
        code:
          type: string
          example: feature_unavailable
    ApiErrorNotFound:
      type: object
      required:
        - status
        - error
        - code
      properties:
        status:
          type: integer
          format: int32
          example: 404
        error:
          type: string
          example: Not Found
        code:
          type: string
          example: object_not_found
    Currency:
      type: string
      example: USD
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BIF
        - BMD
        - BND
        - BOB
        - BRL
        - BSD
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHF
        - CLF
        - CLP
        - CNY
        - COP
        - CRC
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - ISK
        - JMD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KRW
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MUR
        - MVR
        - MWK
        - MXN
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SEK
        - SGD
        - SHP
        - SLL
        - SOS
        - SRD
        - STD
        - SYP
        - SZL
        - THB
        - TJS
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VND
        - VUV
        - WST
        - XAF
        - XCD
        - XOF
        - XPF
        - YER
        - ZAR
        - ZMW
    AttributedUsageRowObject:
      type: object
      required:
        - value
        - rank
        - amount_cents
        - precise_amount_cents
        - events_count
        - split_charge_units
        - charges_usage
      properties:
        value:
          type: string
          description: >-
            Attribution value the usage is attributed to, at the level of the
            `group_by` usage attribution type.
          example: engineering
        rank:
          type: integer
          description: >-
            Rank of the value in the level, starting at 1. Values are ranked by
            amount when `basis` is `amount`, and by units, summed across the
            selected charges, when `basis` is `units`. Values with the same
            amount or units are ranked by value, in ascending order.
          example: 1
        amount_cents:
          type:
            - integer
            - 'null'
          description: >-
            Amount of the usage in cents, rounded to the nearest cent. It is
            `null` when `basis` is `units`.
          example: 1200
        precise_amount_cents:
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: >-
            Amount of the usage in cents, sent as a decimal string. It is `null`
            when `basis` is `units`.
          example: '1200.4567'
        events_count:
          type: integer
          description: Number of events.
          example: 42
        split_charge_units:
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: >-
            Units of the charge split by `split_charge_code`, across all its
            filters and the usage that matches none of them, sent as a decimal
            string. Unlike `charges_usage`, it covers the filters of every page.
            It is `null` when no charge is split.
          example: '15000.5'
        charges_usage:
          type: array
          items:
            $ref: '#/components/schemas/AttributedUsageChargeUsageObject'
          description: >-
            Usage of each charge of the plan, in the order of the charges. A
            charge split by `split_charge_code` has one entry per filter of the
            page selected by `split_filters_offset`, then one for the usage that
            matches none of its filters. The filters of other pages have no
            entry, but their usage still counts in the amount.
    AttributedUsageTotalsObject:
      type: object
      required:
        - amount_cents
        - precise_amount_cents
        - events_count
        - split_charge_units
        - charges_usage
      properties:
        amount_cents:
          type:
            - integer
            - 'null'
          description: >-
            Amount of the usage in cents, rounded to the nearest cent. It is
            `null` when `basis` is `units`.
          example: 1200
        precise_amount_cents:
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: >-
            Amount of the usage in cents, sent as a decimal string. It is `null`
            when `basis` is `units`.
          example: '1200.4567'
        events_count:
          type: integer
          description: Number of events.
          example: 42
        split_charge_units:
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: >-
            Units of the charge split by `split_charge_code`, across all its
            filters and the usage that matches none of them, sent as a decimal
            string. Unlike `charges_usage`, it covers the filters of every page.
            It is `null` when no charge is split.
          example: '15000.5'
        charges_usage:
          type: array
          items:
            $ref: '#/components/schemas/AttributedUsageChargeUsageObject'
          description: >-
            Usage of each charge of the plan, in the order of the charges. A
            charge split by `split_charge_code` has one entry per filter of the
            page selected by `split_filters_offset`, then one for the usage that
            matches none of its filters. The filters of other pages have no
            entry, but their usage still counts in the amount.
    AttributedUsageChargeUsageObject:
      type: object
      required:
        - lago_charge_id
        - charge_code
        - billable_metric_code
        - lago_charge_filter_id
        - charge_filter_values
        - charge_filter_invoice_display_name
        - units
        - amount_cents
        - precise_amount_cents
        - events_count
      properties:
        lago_charge_id:
          type: string
          format: uuid
          description: Unique identifier of the charge, created by Lago.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        charge_code:
          type: string
          description: Code of the charge.
          example: tokens
        billable_metric_code:
          type: string
          description: Code of the billable metric of the charge.
          example: tokens
        lago_charge_filter_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Unique identifier of the charge filter, created by Lago. It is set
            only for the charge split by `split_charge_code`, and is `null` for
            the usage that matches none of its filters.
          example: 1a901a90-1a90-1a90-1a90-1a901a901a90
        charge_filter_values:
          type:
            - object
            - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          description: >-
            Values of the charge filter, by billable metric filter key. It is
            `null` when `lago_charge_filter_id` is `null`.
          example:
            model:
              - opus
        charge_filter_invoice_display_name:
          type:
            - string
            - 'null'
          description: >-
            Name of the charge filter displayed on the invoice. It is `null`
            when `lago_charge_filter_id` is `null` or when the filter has no
            display name.
          example: Opus tokens
        units:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Number of units consumed, sent as a decimal string.
          example: '1250.5'
        amount_cents:
          type:
            - integer
            - 'null'
          description: >-
            Amount of the usage in cents, rounded to the nearest cent. It is
            `null` when `basis` is `units`, or when the charge cannot be priced
            (only charges with the `standard` charge model are priced).
          example: 1200
        precise_amount_cents:
          type:
            - string
            - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: >-
            Amount of the usage in cents, sent as a decimal string. It is `null`
            in the same cases as `amount_cents`.
          example: '1200.4567'
        events_count:
          type: integer
          description: Number of events.
          example: 42
  responses:
    Unauthorized:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnauthorized'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorForbidden'
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.