Retrieve current usage

Retrieve real-time customer usage data for the current open billing period.

GET /customers/{external_customer_id}/current_usage

cURL

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"

curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'

200

{
  "customer_usage": {
    "from_datetime": "2022-07-01T00:00:00Z",
    "to_datetime": "2022-07-31T23:59:59Z",
    "issuing_date": "2022-08-01",
    "amount_cents": 123,
    "taxes_amount_cents": 200,
    "total_amount_cents": 123,
    "charges_usage": [
      {
        "units": "1.0",
        "total_aggregated_units": "1.0",
        "events_count": 10,
        "amount_cents": 123,
        "amount_currency": "EUR",
        "charge": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "charge_model": "graduated",
          "invoice_display_name": "Setup"
        },
        "billable_metric": {
          "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
          "name": "Storage",
          "code": "storage",
          "aggregation_type": "sum_agg"
        },
        "pricing_unit_details": {
          "amount_cents": 200,
          "short_name": "CR",
          "conversion_rate": "0.5"
        },
        "filters": [
          {
            "units": "0.9",
            "total_aggregated_units": "1.0",
            "amount_cents": 1000,
            "events_count": 10,
            "invoice_display_name": "AWS eu-east-1",
            "pricing_unit_details": {
              "amount_cents": 200,
              "short_name": "CR",
              "conversion_rate": "0.5"
            },
            "values": {
              "region": [
                "us-east-1"
              ]
            }
          }
        ],
        "grouped_usage": [
          {
            "amount_cents": 1000,
            "events_count": 10,
            "units": "0.9",
            "total_aggregated_units": "1.0",
            "pricing_unit_details": {
              "amount_cents": 200,
              "short_name": "CR",
              "conversion_rate": "0.5"
            },
            "grouped_by": {},
            "filters": [
              {
                "units": "0.9",
                "total_aggregated_units": "1.0",
                "amount_cents": 1000,
                "events_count": 10,
                "invoice_display_name": "AWS eu-east-1",
                "pricing_unit_details": {
                  "amount_cents": 200,
                  "short_name": "CR",
                  "conversion_rate": "0.5"
                },
                "values": {
                  "region": [
                    "us-east-1"
                  ]
                }
              }
            ]
          }
        ]
      }
    ],
    "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "currency": "EUR"
  }
}

cURL

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"

curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

external_customer_id · string · required

The customer external unique identifier (provided by your own application).

Example:

"5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"

Query Parameters

external_subscription_id · string · required

The unique identifier of the subscription within your application.

Example:

"sub_1234567890"

apply_taxes · boolean · default: true

Optional flag to determine if taxes should be applied. Defaults to true if not provided or if null.

Example:

true

charge_id · string<uuid>

Filter usage to a specific charge by its Lago ID (UUID). Replaces deprecated filter_by_charge_id.

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

charge_code · string

Filter usage to a specific charge by its code. Replaces deprecated filter_by_charge_code.

Example:

"storage"

billable_metric_code · string

Filter usage to a specific billable metric by its code.

Example:

"storage"

group · object

Filter usage by pricing group. Pass key/value pairs as query parameters, e.g. group[cloud]=aws. Replaces deprecated filter_by_group.

Show child attributes

Example:

{ "cloud": "aws" }

filter_by_charge_id · string<uuid>

Filter usage to a specific charge by its Lago ID (UUID).

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

filter_by_charge_code · string

Filter usage to a specific charge by its code.

Example:

"storage"

filter_by_group · object

Filter usage by pricing group. Pass key/value pairs as query parameters, e.g. filter_by_group[cloud]=aws.

Show child attributes

Example:

{ "cloud": "aws" }

full_usage · boolean · default: false

When true, returns usage since subscription start instead of the current billing period. Requires one of charge_id, charge_code, group (or their deprecated filter_by_* equivalents) to be set.

Example:

true

Response

200

application/json

Customer usage

customer_usage · object · required

Show child attributes