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:
| Meter | Unit | Aggregation |
|---|---|---|
bandwidth_bytes | bytes | sum |
function_executions | count | sum |
storage_bytes | bytes | last |
users_total | count | last |
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
Account level: Console Session/JWT, aggregated according to current effective project memberships.
Organization level: active membership, with roles
owner/admin/analyst/billing.Project level: Console project context; the server re-verifies read permission and deletion status before and after the request.
The method name is fixed as
listUsageAggregates(three same-named methods in the JS Console SDK); do not guessgetUsageAggregates()(that is another set of entry points on the Server/Web SDK account/project side — see SDK differences).
Usage workflow
Account level:
account.listUsageAggregates().Organization level:
organizations.listUsageAggregates({ organizationId }).Project level:
projects.listUsageAggregates({ projectId }).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
}]
}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
bytesandcountseparately;sumandlastmust not be re-aggregated with the same method.
Key parameters and returns
quantity = nullmeans insufficient evidence and must never be converted to 0 (?? 0is forbidden); it is one of three distinct states, alongside0and "incomplete".complete=falsemeans the data is not yet closed;freshnessAtis the data freshness watermark (may be null).reasonenum:child_missing(sub-project missing),child_incomplete(sub-project incomplete),source_watermark_unavailable(source watermark cannot be proven).Quota limits are not usage: limits are documented in limits.md; read them separately for display.
Errors and boundaries
Insufficient permission / non-member: 401/403; the organization level requires one of the four roles.
Missing data is a normal state, not an error: render according to
quantity=null/complete=false/reasonand do not retry as if it were a failure.Usage comes from backend stats aggregation, not real-time scanning; buckets near the current moment may not yet be closed.
Starting with 2.7.0, organization usage rollups (
GET /organizations/{organizationId}/usageand aggregation criteria) only count active projects wheredeletionStatusis empty; pending-deletion/deleting projects are excluded from the rollup and project details (appbase release-2.7.0 PR 520).
SDK Category Differences
Console SDK (console-sdk/nodejs.md): the
listUsageAggregates()of theaccount/organizations/projectsservices — the canonical entry point added in 2.6.0.Server SDK / Client SDK (server-sdk/nodejs.md / client-sdk/web.md):
account.getUsageAggregates()andprojects.getUsageAggregates()(similar aggregations at the account/project level, with different method names).The generated name in the Java Console SDK is
getUsageAggregates(new Projects(client).getUsageAggregates(projectId)) — different from the JSlistUsageAggregates; do not use them interchangeably.Legacy criteria (compatible, Console SDK):
new Project(client).getUsage({ startDate, endDate, period })(period1h/1d, returnsdatabasesStorageTotal/filesStorageTotal/ breakdown);storage.getUsage({ range })/storage.getBucketUsage({ bucketId, range });tablesDB.listUsage({ range })/tablesDB.getUsage({ databaseId, range })(range24h/30d/90d). These endpoints target the current business project and cannot directly reuse the aggregation usage Client ofsetProject('console'); see Console Java SDK for a standalone Java Client example. The identically named methods on Databases are deprecated; prefer TablesDB.
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.
- Console (Node.js)
- Java
- REST (curl)
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// The Java Console SDK generated name is getUsageAggregates, different from JS's listUsageAggregates; do not mix them
// Project level:
new io.agentbase.console.services.Projects(consoleClient)
.getUsageAggregates("<projectId>"); // GET /projects/{projectId}/usage/aggregates
// Organization level (Java service class SelfHostedOrganizations, same endpoints as the JS organizations surface):
new io.agentbase.console.services.SelfHostedOrganizations(consoleClient)
.getUsageAggregates("<organizationId>"); // GET /organizations/{organizationId}/usage/aggregates
// Account level (/account/usage/aggregates) has no typed method in console-java; use the REST tab below# all three tiers of aggregation use the Console Session/JWT (Cookie, -b), not the project API key
# Account level:
curl -sS "$APPBASE_ENDPOINT/account/usage/aggregates" \
-b "$APPBASE_CONSOLE_COOKIE"
# Organization level (requires owner / admin / analyst / billing):
curl -sS "$APPBASE_ENDPOINT/organizations/<organizationId>/usage/aggregates" \
-b "$APPBASE_CONSOLE_COOKIE"
# Project level:
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/usage/aggregates" \
-b "$APPBASE_CONSOLE_COOKIE"
# Returns MeterUsageList; quantity=null means "insufficient evidence" and must not be converted to 0Parsing 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.
- Console (Node.js)
- Java
- REST (curl)
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// MeterUsageList / MeterUsage are response models of the console-java artifact (io.agentbase.console.models)
io.agentbase.console.models.MeterUsageList list =
new io.agentbase.console.services.Projects(consoleClient).getUsageAggregates("<projectId>");
for (io.agentbase.console.models.MeterUsage agg : list.getAggregates()) {
if (agg.getQuantity() == null) {
// Insufficient evidence ≠ 0: quantity is a Long, null renders as missing; combine with getComplete() / getReason()
//(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
System.out.println(agg.getMeter() + " " + agg.getQuantity() + " " + agg.getUnit()
+ " complete=" + agg.getComplete() + " freshnessAt=" + agg.getFreshnessAt());
}
// 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 completescurl -sS "$APPBASE_ENDPOINT/projects/<projectId>/usage/aggregates" \
-b "$APPBASE_CONSOLE_COOKIE"
# aggregates[] each item contains meter / meterVersion / quantity(number|null) / unit / aggregation / periodStart / periodEnd / complete / freshnessAt / reason
# quantity=null renders as missing (must not be converted to 0); complete=false means the data is not closedExample Guide
JavaScript (Console three-level usage + Node project usage): examples/javascript.md
Java:examples/java.md