Usage API

Query aggregated usage data across meters and customers.

Query usage

GET/v1/usage

Parameter	Type	Required	Description
`meter`	string	Yes	Meter slug
`customer`	string	Yes	Customer external ID
`page_size`	integer	No	Number of results per page
`page_token`	string	No	Cursor for pagination

Response

json

{
  "meter": { "id": "...", "slug": "api-requests", "event_type": "api_call" },
  "customer_id": "...",
  "period": { "start": "...", "end": "..." },
  "granularity": "hour",
  "groups": [
    {
      "group_key": { "endpoint": "/v1/users" },
      "windows": [
        { "window_start": "...", "window_end": "...", "value": 142.0, "is_final": true }
      ],
      "subtotal": 142.0
    }
  ],
  "total": 142.0
}

Example

bash

curl "https://api.meterd.io/v1/usage?meter=api-requests&customer=cust_123" \
  -H "Authorization: Bearer mtd_adm_..."

Usage summary

GET/v1/usage/summary

Returns aggregated totals per meter for a customer.

Parameter	Type	Required	Description
`customer`	string	Yes	Customer external ID
`start`	string	No	Start of window (ISO 8601 datetime)
`end`	string	No	End of window (ISO 8601 datetime)

Response

json

[
  { "meter_id": "...", "meter_slug": "api-requests", "total_usage": 5420.0 }
]

Usage total

GET/v1/usage/total

Returns only the total aggregated value (no time series or breakdown).

Parameter	Type	Required	Description
`customer`	string	Yes	Customer external ID

Response

json

{ "total": 5420.0 }

Usage comparison

GET/v1/usage/comparison

Compare month-over-month usage for a customer and meter.

Parameter	Type	Required	Description
`customer`	string	Yes	Customer external ID
`meter`	string	Yes	Meter slug

Response

json

{
  "current_total": 847293,
  "previous_total": 723108,
  "delta": 124185,
  "percent_change": 17.17
}

Export usage

GET/v1/usage/export

Export usage data as JSON or CSV.

Parameter	Type	Required	Description
`customer`	string	Yes	Customer external ID
`format`	string	No	"csv" or "json" (default: "json")
`start`	string	No	Start of window (ISO 8601 datetime)
`end`	string	No	End of window (ISO 8601 datetime)

The default time window is the last 30 days. The default page_size is 50,000 events.

When format=csv, the response has Content-Type: text/csv and includes a Content-Disposition header for file download.