Get Usage By Tool V1

Tool-level work breakdown across the tenant’s jobs. Joins ToolExecution → Job to scope by tenant…

GET /api/v1/usage/by-tool

cURL

curl --request GET \
  --url 'https://api.computer.stateset.app/api/v1/usage/by-tool' \
  --header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY"

200

{
  "rows": [
    {
      "tool_name": "string",
      "calls": 1,
      "total_duration_ms": 8,
      "avg_duration_ms": 7.5,
      "error_calls": 1
    }
  ],
  "total_calls": 1
}

Tool-level work breakdown across the tenant’s jobs.

Joins ToolExecution → Job to scope by tenant; aggregates call count, total + average duration, and a heuristic error count per tool name. Useful for spotting whether a slow rollout is ‘computer is slow’ vs. ‘we issue 10x as many bash calls as we used to.‘

Response

UsageByToolResponse

rows · UsageByToolRow[] · required

Sorted by total_duration_ms descending — heaviest tool first.

Show UsageByToolRow

tool_name · string · required

Tool identifier (bash, computer, browser, …).

calls · integer · required

Total invocations across all jobs.

total_duration_ms · integer · required

Sum of duration_ms across calls.

avg_duration_ms · number · required

Mean duration per call.

error_calls · integer · required

Count of calls whose tool_output starts with an ‘error’ marker — best-effort heuristic, not a strict success/fail classification.

total_calls · integer · required

Status codes

Code	Meaning
200	Successful Response

cURL

curl --request GET \
  --url 'https://api.computer.stateset.app/api/v1/usage/by-tool' \
  --header "X-API-Key: $STATESET_COMPUTER_USE_API_KEY"

200

{
  "rows": [
    {
      "tool_name": "string",
      "calls": 1,
      "total_duration_ms": 8,
      "avg_duration_ms": 7.5,
      "error_calls": 1
    }
  ],
  "total_calls": 1
}