Skip to content
Docs
APISign inStart free

Usage tools

MCP tools for Usage: usage_aggregates_list.

  • usage_aggregates_list: List daily usage

usage_aggregates_list

List daily usage. Operation usage.aggregates.list · Brand level · permission usage:read · risk tier read · since M5

Lists the brand's daily usage aggregates in the mode of the request: one per customer, meter, day and attribute set, with the day's sum (quantity), event count, largest quantity (max) and last event (last). Days are calendar days in the entity's time zone; start and end are the instants each spans. Late usage counts on the day it happened.

  • customerId, meter: one customer's or one meter's usage;
  • from, to: the first and last day, inclusive (YYYY-MM-DD).

Newest day first. Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

ArgumentTypeRequiredDescription
limitintegerno(1–100)
starting_afterID (uagg_…)no–
customerIdID (cus_…)noOnly this customer's usage.
meterstringnoOnly this meter's usage. (at most 100 characters)
fromstringnoThe first day, inclusive (YYYY-MM-DD, in the entity's time zone).
tostringnoThe last day, inclusive.
entity_idID (ent_…)noOptional: the brand's legal entity (ent_…); brand_id alone is enough.
brand_idID (brd_…)noThe brand to act on (brd_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.
  • Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
  • Read-only: changes nothing; idempotency_key is ignored.

Errors

Example

A customer's API calls in October

Arguments:

JSON
{
  "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0a1",
  "meter": "api.calls",
  "from": "2026-10-01",
  "to": "2026-10-31",
  "limit": 2,
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}

Result output:

JSON
{
  "object": "list",
  "data": [
    {
      "id": "uagg_01m4v0d9k2j7r5t3w8x6y4z2a2",
      "object": "usage_aggregate",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0a1",
      "meter": "api.calls",
      "period": "2026-10-13",
      "timeZone": "Europe/Zagreb",
      "start": "2026-10-12T22:00:00.000Z",
      "end": "2026-10-13T22:00:00.000Z",
      "attributes": {
        "model": "large"
      },
      "quantity": "4230",
      "eventCount": 37,
      "max": "640",
      "last": {
        "quantity": "120",
        "occurredAt": "2026-10-13T21:40:00.000Z",
        "eventId": "uev_01m4v0d9k2j7r5t3w8x6y4z2a1"
      },
      "amounts": [],
      "updatedAt": "2026-10-13T21:40:01.000Z"
    },
    {
      "id": "uagg_01m4v0d9k2j7r5t3w8x6y4z2a3",
      "object": "usage_aggregate",
      "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
      "livemode": false,
      "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0a1",
      "meter": "api.calls",
      "period": "2026-10-12",
      "timeZone": "Europe/Zagreb",
      "start": "2026-10-11T22:00:00.000Z",
      "end": "2026-10-12T22:00:00.000Z",
      "attributes": {
        "model": "large"
      },
      "quantity": "3910",
      "eventCount": 31,
      "max": "512",
      "last": {
        "quantity": "64",
        "occurredAt": "2026-10-12T20:05:00.000Z",
        "eventId": "uev_01m4v0d9k2j7r5t3w8x6y4z2a0"
      },
      "amounts": [],
      "updatedAt": "2026-10-12T20:05:01.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "uagg_01m4v0d9k2j7r5t3w8x6y4z2a3"
}