Graph Statistics
WarmHub exposes several graph statistics surfaces because dashboards, billing, settings pages, and shape summaries need different levels of detail.
Method names below are the TypeScript spellings. The Python SDK has the same methods in snake_case — client.graph.list_for_caller(...), client.graph.get_stats(...), and so on — with signatures in the Python SDK reference.
Cross-Org Graph Listing
Section titled “Cross-Org Graph Listing”client.graph.listForCaller(opts?) returns graphs across all organizations the caller has access to, with optional limit and sort ('recent' | 'name') parameters.
Use this when you need an account-wide view rather than calling listPage separately for each organization. Note that listForCaller requires an interactive session — it does not accept PAT or component-token auth.
Dashboard List Metadata
Section titled “Dashboard List Metadata”client.graph.listPage(...) returns graph list items with dashboard-oriented metadata:
-
totalis the exact number of active stored identities. -
byKindpartitions those identities intoshape,thing, andassertion.assertioncounts every active assertion — every item whose Shape closure includes Assertion, however it was written — the same setcountreturns forkind: 'assertion'.thingcounts the remaining non-Shape items, so no item is counted twice. -
lastWriteAtis an activity timestamp, not a strict write-history cursor. -
hasErrorsis true when the graph has at least one active subscription whose latest terminal run is a failure. A subsequent successful run clears the flag. Inactive subscriptions are excluded. -
failingSubscriptionNameis present whenhasErrorsis true and the caller holds therepo:configurescope (the scope keeps therepospelling because a graph was formerly called a repo). It names the failing subscription whose failure is the most recent among all currently failing subscriptions.
Use this for graph tiles and organization dashboards.
Exact Single-Graph Stats
Section titled “Exact Single-Graph Stats”client.graph.getStats(...) returns an exact active-item count for one graph.
The total field counts active stored identities. The byKind breakdown partitions them the same way as listPage: assertion counts every active assertion (Shape closure includes Assertion), and thing counts the remaining non-Shape items. The per-shape map is keyed by each item’s declared Shape and counts both ordinary things and assertions under it; an assertion whose declared Shape composes Assertion counts under that Shape, not under Assertion.
Use this for billing, quotas, or graph detail pages that need the per-shape map.
Batch Stats
Section titled “Batch Stats”client.graph.getStatsBatch(orgName, graphNames) returns totals for up to 100 graphs in one request.
Each item in results.items always carries orgName and graphName. The error and byKind fields are both conditional. There are two distinct cases where byKind is absent:
- Error case — when a graph’s count cannot be returned (for example, because counting would be too expensive for a token that can read only part of the graph), the item carries an
errorfield andbyKindis omitted. - Missing or not-visible graph — when a requested graph name does not exist or is not visible to the caller, the item carries
total: 0with noerrorand nobyKind.
Because of the second case, checking item.error alone is not sufficient to determine whether byKind is present. Always guard on item.byKind directly before using it:
const results = await client.graph.getStatsBatch(orgName, graphNames);for (const item of results.items) { if (item.error) { // count unavailable — handle or skip console.warn(item.error.code, item.error.message); continue; } // item.total is safe to use here, but byKind may still be absent // (e.g. the graph was not found or not visible to the caller) if (item.byKind) { // safe to use item.byKind }}The batch result does not include the per-shape map; call getStats(...) for any graph where you need that detail.
Configure Stats
Section titled “Configure Stats”client.graph.getConfigureStats(...) returns settings-page counts such as the number of subscriptions attached to a graph.
Use it before delete or visibility-change flows when the UI needs to explain what graph configuration will be affected.
Shape Instance Counts
Section titled “Shape Instance Counts”client.graph.getShapeInstanceCounts(...) returns thing and assertion counts grouped by shape.
The server computes these totals directly, so callers do not need to page through graph contents to build a shape summary UI.