Docs
Contents

Usage

Overview and use cases

2.6.0 introduces three-level usage aggregation: Account / Organization / Project across three levels, always showingthe most recent 30 UTC days (the current UTC day + the previous 29 days; the response range is fixed at '30d'). Use it for pre-billing estimates, quota proximity checks, and project resource consumption trends.

Four meters:

MeterUnitAggregation
bandwidth_bytesbytessum
function_executionscountsum
storage_bytesbyteslast
users_totalcountlast

This and the legacy metrics (/project/usage, Storage.getUsage, TablesDB.listUsage, etc.) aretwo separate systems: the legacy endpoints are for resource details/compatibility display, with different ranges and response models; do not mix them (see the end of this document).

Prerequisites

Usage workflow

  1. Account level: account.listUsageAggregates().

  2. Organization level: organizations.listUsageAggregates({ organizationId }).

  3. Project level: projects.listUsageAggregates({ projectId }).

  4. Parse the returned MeterUsageList:

{
  range: '30d', periodStart, periodEnd, complete, freshnessAt,
  aggregates: [{
    subjectType: 'project' | 'organization' | 'account',
    subjectId, meter, meterVersion,
    quantity,          // number | null
    unit: 'bytes' | 'count',
    aggregation: 'sum' | 'last',
    periodStart, periodEnd, complete, freshnessAt, reason
  }]
}
  1. Display rules: when switching scope, cancel the old request and clear the old state; do not reuse the previous scope's summary/trends until the new request completes; format bytes and count separately; sum and last must not be re-aggregated with the same method.

Key parameters and returns

Errors and boundaries

SDK Category Differences

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Three-Level Usage Aggregation (Account / Organization / Project)

The three-level aggregation is exclusive to the Console SDK (credentials: Console Session/JWT; project API Keys cannot call it) and has no Node.js (Server)/Web tabs; the organization level requires one of owner / admin / analyst / billing (see Prerequisites). The sdk.forConsole wrapper object of the JS Console SDK does not expose Organizations; for the organization level, import Organizations from the package and instantiate it with a Console Client. Java uses the generated name getUsageAggregates (organization level under SelfHostedOrganizations; account level has no typed method); the release-2.6.0 SDKs for Python / Go have no typed three-level aggregation methods, so those tabs are omitted.

import { Client, Account, Organizations, Projects } from 'agentbase-console-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT!)
    .setProject(process.env.APPBASE_CONSOLE_PROJECT_ID!)
    .setCookie(process.env.APPBASE_SESSION_COOKIE!); // Console Session; do not use a project API Key
const account = new Account(client);
const organizations = new Organizations(client);
const projects = new Projects(client);

await account.listUsageAggregates();
await organizations.listUsageAggregates({ organizationId: '<orgId>' });
await projects.listUsageAggregates({ projectId: '<projectId>' });
// Returns MeterUsageList: range fixed at '30d', aggregates[] contain meter / quantity / complete / freshnessAt / reason

Parsing Responses and Display Rules

Render aggregates[] item by item: quantity=null means "insufficient evidence" and must not be converted to 0; complete=false indicates the data is not yet closed; bytes and count are formatted separately, and sum and last must not be re-aggregated with the same method; when switching scope, cancel the old request and clear the old state. Java responses use MeterUsageList / MeterUsage; this document provides no field-by-field Python / Go response model examples, so those tabs are omitted.

const list = await sdk.forConsole.projects.listUsageAggregates({ projectId: '<projectId>' });
for (const agg of list.aggregates) {
    if (agg.quantity === null) {
        // Insufficient evidence ≠ 0: rendered as missing; combine with agg.complete / agg.reason (child_missing | child_incomplete | source_watermark_unavailable)
        continue;
    }
    // bytes and count are formatted separately; when aggregation is 'sum' or 'last', they cannot be re-aggregated with the same method
    console.log(agg.meter, agg.quantity, agg.unit, agg.complete, agg.freshnessAt);
}
// When switching Account / Organization / Project, cancel the old request and clear old state; do not reuse the previous scope's summary/trends until the new request completes

Example Guide