Skip to content
Kindgi

client.cost

View as Markdown

client.cost — the cost operations.

On AsyncKindgi every method is the same, awaited.

client.cost.aggregate()

Section titled “client.cost.aggregate()”
aggregate(
    *,
    group_by: str,
    limit: int | None = None,
    from_: str | None = None,
    to: str | None = None,
    category: str | None = None,
    provider_id: str | UUID | None = None,
    agent_id: str | UUID | None = None,
    run_id: str | UUID | None = None,
    conversation_id: str | UUID | None = None,
    model: str | None = None,
    served_model: str | None = None,
    root_run_id: str | UUID | None = None,
    flow_id: str | UUID | None = None,
    include_descendants: bool | None = None,
    scope_kind: Literal['tenant', 'org', 'project'] | None = None,
    scope_id: str | UUID | None = None,
    inherit: bool | None = None,
    timeout: float | None = None,
) -> CostAggregateResult
Signature

Aggregate cost across a time window. GET /v1/cost/aggregate

Primary consumer path for dashboards. groupBy is required (comma-separated dimensions from the closed set); time range is required (both from and to, or both omitted for the default last-30-days window echoed back in timeRange). Filters compose on top of the time window. ?scopeKind + ?scopeId narrow the aggregate to a scope: org covers every project in the org, so one call sums an org's spend. It needs read on the scope, and across projects (no scope, the tenant, or an org) it counts only the projects the caller may read, and records with no project; a tenant admin's counts every project. Each group, and the total, carries its cost and its token sums (tokens). groups is ordered by totalUsd, highest first (ties by key), and capped at limit (default 1000): truncated and totalGroups say when there were more, and the totals still cover every record. For every record, page through /v1/cost/records. inherit has no effect on cost records, which always belong to a project.