# client.cost

> client.cost — the cost operations.

`client.cost` — the `cost` operations.

On `AsyncKindgi` every method is the same, awaited.

## `client.cost.aggregate()`

```python signature
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,
    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
```

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.