--- title: "Trace Usage" method: POST path: "/trace/usage" tags: ["Calls"] --- # Trace Usage `POST /trace/usage` Compute per-call usage for a trace, with descendant rollup. ## Request body - TraceUsageReq — Request to compute per-call usage for a trace, with descendant rollup. This endpoint returns usage metrics for each call in the trace, where each call's metrics include the sum of its own usage plus all descendants' usage. Use this for trace view where you want to see rolled-up metrics per call. Note: All matching calls are loaded into memory for aggregation. For very large result sets (>10k calls), consider using more specific filters or pagination at the application layer. - `project_id` string, required - `filter` CallsFilter - `op_names` string[], nullable - `input_refs` string[], nullable - `output_refs` string[], nullable - `parent_ids` string[], nullable - `trace_ids` string[], nullable - `call_ids` string[], nullable - `thread_ids` string[], nullable - `turn_ids` string[], nullable - `trace_roots_only` boolean, nullable - `wb_user_ids` string[], nullable - `wb_run_ids` string[], nullable - `query` Query - `$expr` union, required - AndOperation — Logical AND. All conditions must evaluate to true. Example: ``` { "$and": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - `$and` Operation[], required - union - LiteralOperation — Represents a constant value in the query language. This can be any standard JSON-serializable value. Example: ``` {"$literal": "predict"} ``` - … - GetFieldOperator — Access a field on the traced call. Supports dot notation for nested access, e.g. `summary.usage.tokens`. Only works on fields present in the `CallSchema`, including: - Top-level fields like `op_name`, `trace_id`, `started_at` - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc. Example: ``` {"$getField": "op_name"} ``` - … - ConvertOperation — Convert the input value to a specific type (e.g., `int`, `bool`, `string`). Example: ``` { "$convert": { "input": {"$getField": "inputs.value"}, "to": "int" } } ``` - … - AndOperation — recursive - OrOperation — Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - … - NotOperation — Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation — Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation — Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation — Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation — Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation — Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ``` - … - OrOperation — Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - `$or` Operation[], required - union - LiteralOperation — Represents a constant value in the query language. This can be any standard JSON-serializable value. Example: ``` {"$literal": "predict"} ``` - … - GetFieldOperator — Access a field on the traced call. Supports dot notation for nested access, e.g. `summary.usage.tokens`. Only works on fields present in the `CallSchema`, including: - Top-level fields like `op_name`, `trace_id`, `started_at` - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc. Example: ``` {"$getField": "op_name"} ``` - … - ConvertOperation — Convert the input value to a specific type (e.g., `int`, `bool`, `string`). Example: ``` { "$convert": { "input": {"$getField": "inputs.value"}, "to": "int" } } ``` - … - AndOperation — Logical AND. All conditions must evaluate to true. Example: ``` { "$and": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - … - OrOperation — recursive - NotOperation — Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation — Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation — Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation — Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation — Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation — Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ``` - … - NotOperation — Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - `$not` unknown[], required - unknown - EqOperation — Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - `$eq` unknown[], required - unknown - GtOperation — Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$gt` unknown[], required - unknown - GteOperation — Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - `$gte` unknown[], required - unknown - InOperation — Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - `$in` unknown[], required - unknown - ContainsOperation — Case-insensitive substring match. Not part of MongoDB. Weave-specific addition. Example: ``` { "$contains": { "input": {"$getField": "display_name"}, "substr": {"$literal": "llm"}, "case_insensitive": true } } ``` - `$contains` ContainsSpec, required — Specification for the `$contains` operation. - `input`: The string to search. - `substr`: The substring to search for. - `case_insensitive`: If true, match is case-insensitive. - `input` union, required - LiteralOperation — Represents a constant value in the query language. This can be any standard JSON-serializable value. Example: ``` {"$literal": "predict"} ``` - … - GetFieldOperator — Access a field on the traced call. Supports dot notation for nested access, e.g. `summary.usage.tokens`. Only works on fields present in the `CallSchema`, including: - Top-level fields like `op_name`, `trace_id`, `started_at` - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc. Example: ``` {"$getField": "op_name"} ``` - … - ConvertOperation — Convert the input value to a specific type (e.g., `int`, `bool`, `string`). Example: ``` { "$convert": { "input": {"$getField": "inputs.value"}, "to": "int" } } ``` - … - AndOperation — Logical AND. All conditions must evaluate to true. Example: ``` { "$and": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - … - OrOperation — Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - … - NotOperation — Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation — Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation — Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation — Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation — Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation — recursive - `substr` union, required - LiteralOperation — Represents a constant value in the query language. This can be any standard JSON-serializable value. Example: ``` {"$literal": "predict"} ``` - … - GetFieldOperator — Access a field on the traced call. Supports dot notation for nested access, e.g. `summary.usage.tokens`. Only works on fields present in the `CallSchema`, including: - Top-level fields like `op_name`, `trace_id`, `started_at` - Nested fields like `inputs.input_name`, `summary.usage.tokens`, etc. Example: ``` {"$getField": "op_name"} ``` - … - ConvertOperation — Convert the input value to a specific type (e.g., `int`, `bool`, `string`). Example: ``` { "$convert": { "input": {"$getField": "inputs.value"}, "to": "int" } } ``` - … - AndOperation — Logical AND. All conditions must evaluate to true. Example: ``` { "$and": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "predict"}]}, {"$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 1000}]} ] } ``` - … - OrOperation — Logical OR. At least one condition must be true. Example: ``` { "$or": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "a"}]}, {"$eq": [{"$getField": "op_name"}, {"$literal": "b"}]} ] } ``` - … - NotOperation — Logical NOT. Inverts the condition. Example: ``` { "$not": [ {"$eq": [{"$getField": "op_name"}, {"$literal": "debug"}]} ] } ``` - … - EqOperation — Equality check between two operands. Example: ``` { "$eq": [{"$getField": "op_name"}, {"$literal": "predict"}] } ``` - … - GtOperation — Greater than comparison. Example: ``` { "$gt": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - GteOperation — Greater than or equal comparison. Example: ``` { "$gte": [{"$getField": "summary.usage.tokens"}, {"$literal": 100}] } ``` - … - InOperation — Membership check. Returns true if the left operand is in the list provided as the second operand. Example: ``` { "$in": [ {"$getField": "op_name"}, [{"$literal": "predict"}, {"$literal": "generate"}] ] } ``` - … - ContainsOperation — recursive - `case_insensitive` boolean, nullable - `include_costs` boolean — If true, include cost calculations in the usage. - `limit` integer — Maximum number of calls to process. Acts as a safety limit to prevent unbounded memory usage. ## Response `200` Successful Response - TraceUsageRes — Response with per-call usage metrics (each includes descendant contributions). - `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)