Usage

Track current UTC API usage metrics and view daily usage history.

Overview

The usage sub-client provides daily API usage metrics. current() returns the current UTC date’s counters; history() returns earlier daily counters.

const current = await grantex.usage.current();
const history = await grantex.usage.history({ days: 30 });

---

usage.current()

Get API usage metrics for the current UTC date.

const usage = await grantex.usage.current();

console.log(usage.developerId);        // 'dev_01HXYZ...'
console.log(usage.period);             // '2026-03-07'
console.log(usage.tokenExchanges);     // 142
console.log(usage.authorizations);     // 89
console.log(usage.verifications);      // 1024
console.log(usage.totalRequests);      // 1255

Response: UsageMetrics

developerId · string

The developer organization ID.

period · string

The current UTC date in YYYY-MM-DD format (e.g., '2026-03-07'). The wire field retains the name period for compatibility.

tokenExchanges · number

Number of token exchange operations on this UTC date.

authorizations · number

Number of authorization requests on this UTC date.

verifications · number

Number of token verifications on this UTC date.

totalRequests · number

Total API requests across all endpoints on this UTC date.

---

usage.history()

Retrieve historical usage data for the specified number of days, broken down by day.

const history = await grantex.usage.history({ days: 7 });

for (const entry of history.entries) {
  console.log(entry.date);              // '2026-03-07'
  console.log(entry.tokenExchanges);     // 18
  console.log(entry.authorizations);     // 12
  console.log(entry.verifications);      // 156
  console.log(entry.totalRequests);      // 186
}

Parameters

days · number · required

Number of days of history to retrieve (e.g., 7, 30, 90).

Response: UsageHistory

entries · UsageEntry[]

Array of daily usage entries, ordered newest to oldest.

Each UsageEntry contains:

date · string

The date in YYYY-MM-DD format.

tokenExchanges · number

Number of token exchange operations on this day.

authorizations · number

Number of authorization requests on this day.

verifications · number

Number of token verifications on this day.

totalRequests · number

Total API requests on this day.

---

Full example

import { Grantex } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });

// Check current UTC-date usage
const current = await grantex.usage.current();
console.log(`Date: ${current.period}`);
console.log(`Total requests: ${current.totalRequests}`);
console.log(`  Authorizations: ${current.authorizations}`);
console.log(`  Token exchanges: ${current.tokenExchanges}`);
console.log(`  Verifications: ${current.verifications}`);

// Get last 30 days of usage
const history = await grantex.usage.history({ days: 30 });
const totalMonth = history.entries.reduce((sum, e) => sum + e.totalRequests, 0);
console.log(`\nLast 30 days: ${totalMonth} total requests`);

// Find peak usage day
const peak = history.entries.reduce((max, e) =>
  e.totalRequests > max.totalRequests ? e : max
);
console.log(`Peak day: ${peak.date} (${peak.totalRequests} requests)`);