Read usage

The same counts are readable in three places, one for each reader: your backend sees them in every ruling, your team reads them for all customers through the Management API, and your end users read their own organization's through the public API or the UsageMeter component.

In your backend

Every ruling on a capability the organization holds carries remaining, what is left of the allowance in the current period, and limit, the allowance itself. Read them from the ruling you already make before the work; there is no separate call:

const ruling = shiprev.adjudicate({
  organization_id: claims.organization_id,
  capability_key: 'report_exports',
  quantity: 0, // only asks; counts nothing
  operation: 'read',
});
// ruling.remaining and ruling.limit, when the organization's plan grants the capability

A ruling is made from the local mirror, which follows the region's count once events have been delivered; see When rulings see the usage. When remaining and limit are absent is listed in Rulings.

Across all your customers

Two endpoints of the Management API read the usage of every buyer organization of an application. Both need an operator session of your organization, with any role.

GET /mgt/v1/projects/{projectId}/usage/overview returns one item per buyer organization and capability, and totals:

GET /mgt/v1/projects/{projectId}/usage/events returns the latest usage events, newest occurred_at first: 50 by default, at most 100 with limit, and only one organization's with organization_id. Each event has usage_event_id, organization_id, capability_key, quantity, source, occurred_at and created_at, the time the region recorded it. There is no paging; to keep a full history, store the events in your own systems as you report them.

Both endpoints give amounts as decimal strings rounded to two decimal places.

For your end users

Three endpoints of the public API read the usage of the signed-in end user's own organization. They take an end-user session, and are served on your brand domain under /rest, like the rest of the public API.

GET /public/v1/usage/summary returns the organization's wallet_balance and one item per capability:

GET /public/v1/usage/series returns the daily usage of one capability, capability_key, over the last days days: 7 by default, from 1 to 92. Days are UTC calendar days ending today, oldest first, and a day without usage is 0.

GET /public/v1/usage/events lists the organization's usage events of one capability, capability_key, newest first: limit per page, 50 by default and at most 100. Pass the next_cursor of a page as cursor to read the next one; it is null on the last page.

These three give amounts as decimal strings with six decimal places.

The UsageMeter component

The React component UsageMeter reads the usage summary and shows each capability's use against its allowance, with a bar, inside your own pages. Place it inside ShipRevProvider, which sends its request through your own origin as described in The React components:

import { UsageMeter } from '@shiprev/react';

export function UsagePage() {
  return <UsageMeter capabilityKeys={['report_exports', 'llm_tokens']} showWalletBalance />;
}

UsageMeter only displays. Whether a call is allowed is always decided by your backend's ruling.

Where to go from here