Retrieve a usage record

Operation ID: getUsage

Group: Accounting › Usage

Open in the interactive reference

GET /accounting/usages/{id}

Read-only: Reads and returns; changes nothing.

Retrieves a usage record.

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.
id path string yes The unique identifier of the usage record you want to retrieve.

Response

200 Success

Under data (getUsageOutput):

Field Type Required Description
id string yes The unique identifier for the usage record.
usageNumber string no The usage number, unique within the tenant. Absent while none has been assigned.
usageIdentifier string no The external identifier for this usage record, as supplied at ingestion.
date date-time yes The date and time the usage occurred, without a time zone. Format YYYY-MM-DDTHH:mm:ss.
description string no A free-form description of the usage record. Absent when none is set.
productIdentifier string no The product code or identifier this usage is attributed to, as supplied at ingestion.
billableComponentId string no The billable component this usage is attributed to. Absent until it is resolved. There is no endpoint for it.
usageComponent string no The billable component's name or identifier, included so you do not need a second read.
quantity decimal yes The quantity of usage recorded, in unitOfMeasure.
unitOfMeasure string no The unit the quantity is measured in, for example 'Hour', 'GB' or 'Call'.
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.
status string yes The lifecycle status of the usage record. Possible values: 'pending', 'processed', 'error', 'invoiced', 'pendingRebill', 'rebilled', 'staged', 'skipped'.
usagePeriodId string yes The unique identifier for the usage period this record belongs to. There is no endpoint for it.
customFields UnknownObject no Custom data recorded on this usage record, as a JSON object. Absent when none was set. Free-form JSON object.
orderIndex number no The position of this usage record within the batch it was created in. Absent when not known.
lastModifiedDate date-time yes The date and time the usage record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. 
{
  "data": {
    "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"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Errors

Code Status
NOT_FOUND 400

Statuses