List usage records

Operation ID: listUsage

Group: Accounting › Usage

Open in the interactive reference

GET /accounting/usages

Read-only: Reads and returns; changes nothing.

Lists usage records. This collection does not follow the standard rules in Pagination and querying. Page with pageSize and cursor, not page[size] and page[cursor]. Filter with the query parameters listed below, such as status, not filter[field][op].

The response has the records in data.items and the next page's cursor in data.pagination.nextCursor. There is no sort or fields.

This endpoint ignores any query parameter it does not declare, and returns no error. A request that follows the standard rules gets the first page, unfiltered, every time.

Parameters

Name In Type Required Description
Api-Version header string · v1 yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
status query string no Limits results to usage records with this status. Accepted values: 'pending', 'processed', 'error', 'invoiced', 'pendingRebill', 'rebilled', 'staged', 'skipped'. Omit for every status.
unitOfMeasure query string no Limits results to usage records in this unit, for example 'Hour', 'GB' or 'Call'. Omit for every unit.
usagePeriodId query string no Limits results to usage records in the usage period with this identifier. An identifier matching no usage period returns an empty page.
billableComponentId query string no Limits results to usage records attributed to the billable component with this identifier. An identifier matching no billable component returns an empty page.
dateFrom query string no Limits results to usage records whose date is on or after this bound. Use format YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ. A time zone is converted to UTC before matching.
dateTo query string no Limits results to usage records whose date is on or before this bound. Use format YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ. A time zone is converted to UTC before matching.
lastModifiedFrom query string no Limits results to usage records changed on or after this time, in UTC. Use format YYYY-MM-DDTHH:mm:ss.sssZ.
cursor query string no The cursor from the previous response's data.pagination.nextCursor. Omit for the first page.
pageSize query number no The number of usage records per page. Defaults to 50. A value above 200 is treated as 200, not rejected.

Response

200 Success

Under data (listUsageOutput):

Field Type Required Description
items array<object> yes The usage records on this page, newest first. An empty array when nothing matches.
items[].id string yes The unique identifier for the usage record.
items[].usageNumber string no The usage number, unique within the tenant. Absent while none has been assigned.
items[].usageIdentifier string no The external identifier for this usage record, as supplied at ingestion.
items[].date date-time yes The date and time the usage occurred, without a time zone. Format YYYY-MM-DDTHH:mm:ss.
items[].description string no A free-form description of the usage record. Absent when none is set.
items[].productIdentifier string no The product code or identifier this usage is attributed to, as supplied at ingestion.
items[].billableComponentId string no The billable component this usage is attributed to. Absent until it is resolved. There is no endpoint for it.
items[].usageComponent string no The billable component's name or identifier, included so you do not need a second read.
items[].quantity decimal yes The quantity of usage recorded, in unitOfMeasure.
items[].unitOfMeasure string no The unit the quantity is measured in, for example 'Hour', 'GB' or 'Call'.
items[].unitPrice decimal yes The price per unit for this usage. This record has no currency field. The currency is on the subscription or contract this usage bills against.
items[].status string yes The lifecycle status of the usage record. Possible values: 'pending', 'processed', 'error', 'invoiced', 'pendingRebill', 'rebilled', 'staged', 'skipped'.
items[].usagePeriodId string yes The unique identifier for the usage period this record belongs to. There is no endpoint for it.
items[].customFields UnknownObject no Custom data recorded on this usage record, as a JSON object. Absent when none was set. Free-form JSON object.
items[].orderIndex number no The position of this usage record within the batch it was created in. Absent when not known.
items[].lastModifiedDate date-time yes The date and time the usage record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
pagination object yes The pagination cursor for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as the cursor query parameter. Absent on the last page.
pagination.hasMore boolean yes True when more usage records remain beyond this page. 
{
  "data": {
    "items": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "usageNumber": "<usageNumber>",
        "usageIdentifier": "<usageIdentifier>",
        "date": "2026-01-15T09:30:00.000Z",
        "description": "<description>",
        "productIdentifier": "<productIdentifier>",
        "billableComponentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "usageComponent": "<usageComponent>",
        "quantity": "19.99",
        "unitOfMeasure": "<unitOfMeasure>",
        "unitPrice": "19.99",
        "status": "<status>",
        "usagePeriodId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "customFields": {},
        "orderIndex": 0,
        "lastModifiedDate": "2026-01-15T09:30:00.000Z"
      }
    ],
    "pagination": {
      "nextCursor": "<nextCursor>",
      "hasMore": true
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
INVALID_DATE_FILTER 400

Statuses