Retrieve usages for an invoice as PDF

Retrieves usages record for an invoice in PDF file format. This endpoint is part of the Usages API for Automated Metered Billing.

For Usage-Based Billing invoices, you can optionally group a metered feature's usage by its configured group-by attributes and choose daily or full-period aggregation for that feature. Automated Metered Billing continues to render the existing ungrouped usage PDF.

Aggregation windows in the usage PDF

The invoice period is the reporting range for the PDF, and only usage within the invoice period is included. For each metered feature in group_by[feature_id], group_by[window_size] at the same position controls how its usage is aggregated:

• day (default): Usage is aggregated into calendar-day windows in UTC. A calendar day runs from 00:00:00 UTC through 23:59:59 UTC, so the first and last days can contain usage for only part of the day. Each row displays its date.
• none: Usage is aggregated once for the full invoice period. The table has no date column. Instead, it has one column for each group-by attribute and one row for each distinct set of attribute values.

Metered features that are not listed in group_by[feature_id] always use daily aggregation.

Daily aggregation example

For an invoice period from January 12, 2026 10:45:00 UTC to January 25, 2026 10:45:00 UTC, group_by[window_size][0]=day assigns the corresponding metered feature's usage to these calendar-day windows:

• January 12: usage from January 12 10:45:00 UTC through January 12 23:59:59 UTC
• January 13 through January 24: usage from 00:00:00 UTC through 23:59:59 UTC on each day
• January 25: usage from January 25 00:00:00 UTC through January 25 10:45:00 UTC

The PDF displays only the calendar date for each daily total.

Use Cases