Tools
Get a tool's usage and cost
Returns the tool’s calls, failures, cost and tokens since sinceMs, and the agents that called it most among those you can read; calls from agents you cannot read are counted in hiddenCallerCount, never named. Requires permissions agents:read and tools:read.
GET
/
api
/
v3
/
tools
/
{toolId}
/
usage
Get a tool's usage and cost
curl --request GET \
--url https://api.forge.gloo.com/api/v3/tools/{toolId}/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.forge.gloo.com/api/v3/tools/{toolId}/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.forge.gloo.com/api/v3/tools/{toolId}/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.forge.gloo.com/api/v3/tools/{toolId}/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.forge.gloo.com/api/v3/tools/{toolId}/usage"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.forge.gloo.com/api/v3/tools/{toolId}/usage")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.forge.gloo.com/api/v3/tools/{toolId}/usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": {
"toolId": "<string>",
"since": 123,
"calls": 123,
"failures": 123,
"costCents": 123,
"inputTokens": 123,
"outputTokens": 123,
"topCallers": [
{
"agentId": "<string>",
"agentName": "<string>",
"count": 123
}
],
"hiddenCallerCount": 123
},
"meta": {
"requestId": "<string>",
"partial": true,
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "bad_request",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "forbidden",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "resource_missing",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "internal_error",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.
v2 compatibility notes
GET /api/v2/tools/getUsage?id=<toolId>&sinceMs= returns a tool’s usage and cost since sinceMs.
Authority
You needagents:read and tools:read at the platform scope. A missing, draft or archived tool answers 404 resource_missing; an unavailable store is a 500, never a 404. A repeated or out-of-range parameter is 400 bad_request.
What it returns
calls, failures, costCents, inputTokens and outputTokens since since, and topCallers: the agents that called it most, among those you can read. Calls from agents you cannot read are counted in hiddenCallerCount, never named. sinceMs is an epoch time in milliseconds within the last 90 days (default seven days ago). meta.partial is true when the window held more than 5,000 calls, or when the calls read reached the read budget first (large call payloads); the counts then cover the newest calls only.Authorizations
BearerAuthPlatformApiKeyPersonalKey
Query Parameters
⌘I
Get a tool's usage and cost
curl --request GET \
--url https://api.forge.gloo.com/api/v3/tools/{toolId}/usage \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.forge.gloo.com/api/v3/tools/{toolId}/usage"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.forge.gloo.com/api/v3/tools/{toolId}/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.forge.gloo.com/api/v3/tools/{toolId}/usage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.forge.gloo.com/api/v3/tools/{toolId}/usage"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.forge.gloo.com/api/v3/tools/{toolId}/usage")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.forge.gloo.com/api/v3/tools/{toolId}/usage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": {
"toolId": "<string>",
"since": 123,
"calls": 123,
"failures": 123,
"costCents": 123,
"inputTokens": 123,
"outputTokens": 123,
"topCallers": [
{
"agentId": "<string>",
"agentName": "<string>",
"count": 123
}
],
"hiddenCallerCount": 123
},
"meta": {
"requestId": "<string>",
"partial": true,
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "bad_request",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "forbidden",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "resource_missing",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "internal_error",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}{
"error": {
"code": "unauthorized",
"message": "<string>",
"docUrl": "<string>",
"reason": "requester_unavailable",
"requiredPermission": "<string>",
"personRequired": true,
"decisionId": "<string>",
"capHeadroom": {
"remainingCents": 123,
"capCents": 123,
"consumedCents": 123,
"estimateCents": 123
},
"details": [
{
"path": "<string>",
"param": "<string>",
"message": "<string>",
"code": "required"
}
]
},
"meta": {
"requestId": "<string>",
"hasMore": true,
"nextCursor": "<string>",
"asOf": 123
}
}
