Skip to main content
GET
Retrieve customer attributed usage

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. The subscription must be active.

Example:

"sub_1234567890"

group_by
string
required

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.

Example:

"team"

filters
object

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.

Example:
from_datetime
string<date-time>

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.

Example:

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

to_datetime
string<date-time>

End of the period, in ISO 8601 format. It must be sent together with from_datetime.

Example:

"2022-04-30T23:59:59Z"

charge_codes[]
string[]

Codes of the charges of the plan to include. All the supported charges are included when it is not sent.

Example:
split_charge_code
string

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.

Example:

"tokens"

split_filters_offset
integer
default:0

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 range: 0 <= x <= 20000
Example:

10

search_term
string

Filter the attribution values by search term, up to 100 characters. The totals are not affected by the search.

Maximum string length: 100
Example:

"eng"

basis
enum<string>
default:units

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.

Available options:
units,
amount
Example:

"amount"

page
integer

Page number. Defaults to 1. A value that is not a positive integer, such as 0, returns the first page.

Example:

1

per_page
integer
default:50

Number of attribution values per page, between 1 and 100.

Required range: 1 <= x <= 100
Example:

20

Response

Customer attributed usage

attributed_usage
object
required
meta
object
required