Retrieve past usage

GET

customers

{external_customer_id}

past_usage

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/past_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'

{
  "usage_periods": [
    {
      "customer_usage": {
        "from_datetime": "2022-07-01T00:00:00Z",
        "to_datetime": "2022-07-31T23:59:59Z",
        "issuing_date": "2022-08-01",
        "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "currency": "EUR",
        "amount_cents": 123,
        "taxes_amount_cents": 200,
        "total_amount_cents": 123,
        "charges_usage": [
          {
            "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"
            },
            "filters": [
              {
                "units": "0.9",
                "amount_cents": 1000,
                "events_count": 10,
                "invoice_display_name": "AWS eu-east-1",
                "values": {
                  "region": "us-east-1"
                }
              }
            ],
            "grouped_usage": [
              {
                "amount_cents": 1000,
                "events_count": 10,
                "units": "0.9",
                "grouped_by": {},
                "filters": [
                  {
                    "units": "0.9",
                    "amount_cents": 1000,
                    "events_count": 10,
                    "invoice_display_name": "AWS eu-east-1",
                    "values": {
                      "region": "us-east-1"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "current_page": 2,
    "next_page": 3,
    "prev_page": 1,
    "total_pages": 4,
    "total_count": 70
  }
}

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/past_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

page

integer

Page number.

Example:

1

per_page

integer

Number of records per page.

Example:

20

external_subscription_id

string

required

The unique identifier of the subscription within your application.

Example:

"sub_1234567890"

billable_metric_code

string

Billable metric code filter to apply to the charge usage

Example:

"cpu"

periods_count

integer

Number of past billing period to returns in the result

Example:

5

Response

200

application/json

Customer past usage

usage_periods

object[]

required

usage_periods.customer_usage

object

required

usage_periods.customer_usage.from_datetime

string

required

The lower bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).

Example:

"2022-07-01T00:00:00Z"

usage_periods.customer_usage.to_datetime

string

required

The upper bound of the billing period, expressed in the ISO 8601 datetime format in Coordinated Universal Time (UTC).

Example:

"2022-07-31T23:59:59Z"

usage_periods.customer_usage.issuing_date

string

required

The date of creation of the invoice.

Example:

"2022-08-01"

usage_periods.customer_usage.amount_cents

integer

required

The amount in cents, tax excluded.

Example:

123

usage_periods.customer_usage.taxes_amount_cents

integer

required

The tax amount in cents.

Example:

200

usage_periods.customer_usage.total_amount_cents

integer

required

The total amount in cents, tax included.

Example:

123

usage_periods.customer_usage.charges_usage

object[]

required

Array of charges that comprise the current usage. It contains detailed information about individual charge items associated with the usage.

usage_periods.customer_usage.charges_usage.units

string

required

The number of units consumed by the customer for a specific charge item.

Example:

"1.0"

usage_periods.customer_usage.charges_usage.events_count

integer

required

The quantity of usage events that have been recorded for a particular charge during the specified time period. These events may also be referred to as the number of transactions in some contexts.

Example:

10

usage_periods.customer_usage.charges_usage.amount_cents

integer

required

The amount in cents, tax excluded, consumed by the customer for a specific charge item.

Example:

123

usage_periods.customer_usage.charges_usage.amount_currency

enum<string>

required

The currency of a usage item consumed by the customer.

Available options:

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,

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,

SZL,

THB,

TJS,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

Example:

"USD"

usage_periods.customer_usage.charges_usage.charge

object

required

Object listing all the properties for a specific charge item.

usage_periods.customer_usage.charges_usage.billable_metric

object

required

The related billable metric object.

usage_periods.customer_usage.charges_usage.filters

object[]

Array of filter object, representing multiple dimensions for a charge item.

usage_periods.customer_usage.charges_usage.filters.units

string

The number of units consumed for a specific charge filter related to a charge item.

Example:

"0.9"

usage_periods.customer_usage.charges_usage.filters.amount_cents

integer

The amount in cents, tax excluded, consumed for a specific charge filter related to a charge item.

Example:

1000

usage_periods.customer_usage.charges_usage.filters.events_count

integer

The quantity of usage events that have been recorded for a particular charge filter during the specified time period. These events may also be referred to as the number of transactions in some contexts.

Example:

10

usage_periods.customer_usage.charges_usage.filters.invoice_display_name

string

Specifies the name that will be displayed on an invoice.

Example:

"AWS eu-east-1"

usage_periods.customer_usage.charges_usage.filters.values

object

List of filter values applied to the usage.

Example:

{ "region": "us-east-1" }

usage_periods.customer_usage.charges_usage.grouped_usage

object[]

Array of aggregated fees, grouped by the event properties defined in a standard charge model.

usage_periods.customer_usage.lago_invoice_id

string | null

A unique identifier associated with the invoice related to this particular usage record.

Example:

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

usage_periods.customer_usage.currency

enum<string>

The currency of the customer's current usage.

Available options:

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,

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,

SZL,

THB,

TJS,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VND,

VUV,

WST,

XAF,

XCD,

XOF,

XPF,

YER,

ZAR,

ZMW

Example:

"USD"

meta

object

required

Was this page helpful?

Suggest edits Raise issue

Retrieve current usage The customer object

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/past_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json'

{
  "usage_periods": [
    {
      "customer_usage": {
        "from_datetime": "2022-07-01T00:00:00Z",
        "to_datetime": "2022-07-31T23:59:59Z",
        "issuing_date": "2022-08-01",
        "lago_invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "currency": "EUR",
        "amount_cents": 123,
        "taxes_amount_cents": 200,
        "total_amount_cents": 123,
        "charges_usage": [
          {
            "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"
            },
            "filters": [
              {
                "units": "0.9",
                "amount_cents": 1000,
                "events_count": 10,
                "invoice_display_name": "AWS eu-east-1",
                "values": {
                  "region": "us-east-1"
                }
              }
            ],
            "grouped_usage": [
              {
                "amount_cents": 1000,
                "events_count": 10,
                "units": "0.9",
                "grouped_by": {},
                "filters": [
                  {
                    "units": "0.9",
                    "amount_cents": 1000,
                    "events_count": 10,
                    "invoice_display_name": "AWS eu-east-1",
                    "values": {
                      "region": "us-east-1"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "meta": {
    "current_page": 2,
    "next_page": 3,
    "prev_page": 1,
    "total_pages": 4,
    "total_count": 70
  }
}

API Reference

Authorizations

Path Parameters

Query Parameters

Response