Returns the usage records that match the given filters.

POST /accounting/usages/search

Group: Accounting › Usage · Operation ID: searchUsage

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "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.

Request body

Required, application/json: searchUsageInput.

Field Type Required Description
filters object no The filters to apply. A usage record must match every filter you send. Omit to return all usage records.
filters.id string no Limits results to the usage record with this identifier.
filters.usageNumber string no Limits results to the usage record with this usage number.
filters.usageIdentifier string no Limits results to usage records with this external identifier.
filters.productIdentifier string no Limits results to usage records with this product code or identifier.
filters.status string no Limits results to usage records with this status. Accepted values: 'pending', 'processed', 'error', 'invoiced', 'pendingRebill', 'rebilled', 'staged', 'skipped'. Any other value matches nothing.
filters.unitOfMeasure string no Limits results to usage records in this unit, for example 'Hour', 'GB' or 'Call'.
filters.usagePeriodId string no Limits results to usage records in the usage period with this identifier. An identifier matching no usage period returns an empty page.
filters.billableComponentId 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.
filters.date object no Limits results to usage records whose date falls in this range. Omit either bound to leave that side open. Both bounds are inclusive.
filters.date.start string no The earliest date to include. Use format YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ. A time zone is converted to UTC before matching.
filters.date.end string no The latest date to include. Use format YYYY-MM-DD or YYYY-MM-DDTHH:mm:ss.sssZ. A time zone is converted to UTC before matching.
page object no The pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit for the first page.
page.size number no The number of usage records per page. Defaults to 50. A value above 200 is treated as 200, not rejected.

Example:

{
  "filters": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "usageNumber": "<usageNumber>",
    "usageIdentifier": "<usageIdentifier>",
    "productIdentifier": "<productIdentifier>",
    "status": "<status>",
    "unitOfMeasure": "<unitOfMeasure>",
    "usagePeriodId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "billableComponentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "date": {
      "start": "<start>",
      "end": "<end>"
    }
  },
  "page": {
    "cursor": "<cursor>",
    "size": 0
  }
}

Response

200 Success

Under data (searchUsageOutput):

Field Type Required Description
items array of 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 string (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 string (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 string (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.
items[].orderIndex number no The position of this usage record within the batch it was created in. Absent when not known.
items[].lastModifiedDate string (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 page.cursor. Absent on the last page.
pagination.hasMore boolean yes True when more usage records remain beyond this page.

Errors

Code Status
INVALID_DATE_FILTER 400

Statuses