---
title: "Calls Usage"
method: POST
path: "/calls/usage"
tags: ["Calls"]
---

# Calls Usage

`POST /calls/usage`

Compute aggregated usage for multiple root calls, with descendant rollup.

## Request body

- CallsUsageReq — Request to compute aggregated usage for multiple root calls. This endpoint returns usage metrics for each requested root call, where each root's metrics include the sum of its own usage plus all descendants' usage. Note: All matching calls are loaded into memory for aggregation. For very large result sets (>10k calls), consider batching root call IDs or using narrower filters at the application layer.
  - `project_id` string, required
  - `call_ids` string[], required — Root call IDs to aggregate. Each result key corresponds to one input call ID.
  - `include_costs` boolean — If true, include cost calculations in the usage.
  - `limit` integer — Maximum number of calls to process across all traces. Acts as a safety limit to prevent unbounded memory usage.

## Response `200`

Successful Response

- CallsUsageRes — Response with aggregated usage metrics per root call.
  - `call_usage` object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/wandb/apis/fastapi.md) · [All operations](https://skmtc.net/wandb/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wandb/fastapi/versions/56745769989b/schema)