Skip to content

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.

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.

client.graph.listPage(...) returns graph list items with dashboard-oriented metadata:

  • total is the exact number of active stored identities.

  • byKind partitions those identities into shape, thing, and assertion. assertion counts every active assertion — every item whose Shape closure includes Assertion, however it was written — the same set count returns for kind: 'assertion'. thing counts the remaining non-Shape items, so no item is counted twice.

  • lastWriteAt is an activity timestamp, not a strict write-history cursor.

  • hasErrors is 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.

  • failingSubscriptionName is present when hasErrors is true and the caller holds the repo:configure scope (the scope keeps the repo spelling 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.

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.

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 error field and byKind is 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: 0 with no error and no byKind.

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.

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.

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.