Trace Usage

Compute per-call usage for a trace, with descendant rollup.

POST /trace/usage

Trace Usage

cURL

curl --request POST \
  --url https://api.example.com/trace/usage \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": "<string>",
  "filter": {
    "op_names": [
      "<string>"
    ],
    "input_refs": [
      "<string>"
    ],
    "output_refs": [
      "<string>"
    ],
    "parent_ids": [
      "<string>"
    ],
    "trace_ids": [
      "<string>"
    ],
    "call_ids": [
      "<string>"
    ],
    "thread_ids": [
      "<string>"
    ],
    "turn_ids": [
      "<string>"
    ],
    "trace_roots_only": true,
    "wb_user_ids": [
      "<string>"
    ],
    "wb_run_ids": [
      "<string>"
    ]
  },
  "query": {
    "$expr": {
      "$and": [
        {
          "$literal": "<string>"
        }
      ]
    }
  },
  "include_costs": false,
  "limit": 10000
}
'

import requests

url = "https://api.example.com/trace/usage"

payload = {
    "project_id": "<string>",
    "filter": {
        "op_names": ["<string>"],
        "input_refs": ["<string>"],
        "output_refs": ["<string>"],
        "parent_ids": ["<string>"],
        "trace_ids": ["<string>"],
        "call_ids": ["<string>"],
        "thread_ids": ["<string>"],
        "turn_ids": ["<string>"],
        "trace_roots_only": True,
        "wb_user_ids": ["<string>"],
        "wb_run_ids": ["<string>"]
    },
    "query": { "$expr": { "$and": [{ "$literal": "<string>" }] } },
    "include_costs": False,
    "limit": 10000
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    project_id: '<string>',
    filter: {
      op_names: ['<string>'],
      input_refs: ['<string>'],
      output_refs: ['<string>'],
      parent_ids: ['<string>'],
      trace_ids: ['<string>'],
      call_ids: ['<string>'],
      thread_ids: ['<string>'],
      turn_ids: ['<string>'],
      trace_roots_only: true,
      wb_user_ids: ['<string>'],
      wb_run_ids: ['<string>']
    },
    query: {$expr: {$and: [{$literal: '<string>'}]}},
    include_costs: false,
    limit: 10000
  })
};

fetch('https://api.example.com/trace/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/trace/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'project_id' => '<string>',
    'filter' => [
        'op_names' => [
                '<string>'
        ],
        'input_refs' => [
                '<string>'
        ],
        'output_refs' => [
                '<string>'
        ],
        'parent_ids' => [
                '<string>'
        ],
        'trace_ids' => [
                '<string>'
        ],
        'call_ids' => [
                '<string>'
        ],
        'thread_ids' => [
                '<string>'
        ],
        'turn_ids' => [
                '<string>'
        ],
        'trace_roots_only' => true,
        'wb_user_ids' => [
                '<string>'
        ],
        'wb_run_ids' => [
                '<string>'
        ]
    ],
    'query' => [
        '$expr' => [
                '$and' => [
                                [
                                                                '$literal' => '<string>'
                                ]
                ]
        ]
    ],
    'include_costs' => false,
    'limit' => 10000
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/trace/usage"

	payload := strings.NewReader("{\n  \"project_id\": \"<string>\",\n  \"filter\": {\n    \"op_names\": [\n      \"<string>\"\n    ],\n    \"input_refs\": [\n      \"<string>\"\n    ],\n    \"output_refs\": [\n      \"<string>\"\n    ],\n    \"parent_ids\": [\n      \"<string>\"\n    ],\n    \"trace_ids\": [\n      \"<string>\"\n    ],\n    \"call_ids\": [\n      \"<string>\"\n    ],\n    \"thread_ids\": [\n      \"<string>\"\n    ],\n    \"turn_ids\": [\n      \"<string>\"\n    ],\n    \"trace_roots_only\": true,\n    \"wb_user_ids\": [\n      \"<string>\"\n    ],\n    \"wb_run_ids\": [\n      \"<string>\"\n    ]\n  },\n  \"query\": {\n    \"$expr\": {\n      \"$and\": [\n        {\n          \"$literal\": \"<string>\"\n        }\n      ]\n    }\n  },\n  \"include_costs\": false,\n  \"limit\": 10000\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/trace/usage")
  .header("Content-Type", "application/json")
  .body("{\n  \"project_id\": \"<string>\",\n  \"filter\": {\n    \"op_names\": [\n      \"<string>\"\n    ],\n    \"input_refs\": [\n      \"<string>\"\n    ],\n    \"output_refs\": [\n      \"<string>\"\n    ],\n    \"parent_ids\": [\n      \"<string>\"\n    ],\n    \"trace_ids\": [\n      \"<string>\"\n    ],\n    \"call_ids\": [\n      \"<string>\"\n    ],\n    \"thread_ids\": [\n      \"<string>\"\n    ],\n    \"turn_ids\": [\n      \"<string>\"\n    ],\n    \"trace_roots_only\": true,\n    \"wb_user_ids\": [\n      \"<string>\"\n    ],\n    \"wb_run_ids\": [\n      \"<string>\"\n    ]\n  },\n  \"query\": {\n    \"$expr\": {\n      \"$and\": [\n        {\n          \"$literal\": \"<string>\"\n        }\n      ]\n    }\n  },\n  \"include_costs\": false,\n  \"limit\": 10000\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/trace/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"project_id\": \"<string>\",\n  \"filter\": {\n    \"op_names\": [\n      \"<string>\"\n    ],\n    \"input_refs\": [\n      \"<string>\"\n    ],\n    \"output_refs\": [\n      \"<string>\"\n    ],\n    \"parent_ids\": [\n      \"<string>\"\n    ],\n    \"trace_ids\": [\n      \"<string>\"\n    ],\n    \"call_ids\": [\n      \"<string>\"\n    ],\n    \"thread_ids\": [\n      \"<string>\"\n    ],\n    \"turn_ids\": [\n      \"<string>\"\n    ],\n    \"trace_roots_only\": true,\n    \"wb_user_ids\": [\n      \"<string>\"\n    ],\n    \"wb_run_ids\": [\n      \"<string>\"\n    ]\n  },\n  \"query\": {\n    \"$expr\": {\n      \"$and\": [\n        {\n          \"$literal\": \"<string>\"\n        }\n      ]\n    }\n  },\n  \"include_costs\": false,\n  \"limit\": 10000\n}"

response = http.request(request)
puts response.read_body

200

{
  "call_usage": {},
  "unfinished_call_ids": [
    "<string>"
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Body

application/json

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 · object | null

Filter to select calls. Typically use trace_ids to get all calls in a trace.

Show child attributes

query · Query · object | null

Additional query conditions for filtering calls.

Show child attributes

include_costs · boolean · default: false

If true, include cost calculations in the usage.

limit · integer · default: 10000

Maximum number of calls to process. Acts as a safety limit to prevent unbounded memory usage.

Response

200

application/json

Successful Response

Response with per-call usage metrics (each includes descendant contributions).

call_usage · Call Usage · object

Show child attributes

unfinished_call_ids · string[]