NetBird Full API Reference + Read-Only MCP Prototype
GET/api/agent-network/usage/overview

Agent Network usage overview

Returns agent-network token and cost usage aggregated into time buckets, server-side filtered. Usage is always collected (independent of log collection). Callers without the account-wide grant are not denied - the response is scoped to their own usage (any user_id or group_id filter is overridden).

8 parameters
granularitystringoptional
Time bucket width. Defaults to day.
Allowed:dayweekmonthDefault:day
start_datestringoptional
Filter by timestamp >= start_date (RFC3339 format).
end_datestringoptional
Filter by timestamp <= end_date (RFC3339 format).
user_idstringoptional
Filter by user ID.
session_idstringoptional
Filter to a single conversation / coding session id.
group_idarray<string>optional
Filter by authorising group id. Repeat for multiple (matches any).
provider_idarray<string>optional
Filter by resolved provider id. Repeat for multiple (matches any).
modelarray<string>optional
Filter by model. Repeat for multiple (matches any).

4 status codes
200A JSON array of aggregated usage buckets, ordered oldest-first.
cache_cost_usdnumberrequired
Portion of cost_usd billed for prompt-cache usage in the bucket.
cache_creation_cost_usdnumberrequired
Total cost of prompt-cache write tokens in the bucket.
cache_creation_tokensintegerrequired
Total prompt-cache write tokens in the bucket.
cached_input_cost_usdnumberrequired
Total cost of prompt-cache read tokens in the bucket.
cached_input_tokensintegerrequired
Total prompt-cache read tokens in the bucket.
cost_usdnumberrequired
Total estimated USD spend in the bucket.
input_cost_usdnumberrequired
Total cost of non-cached input tokens in the bucket.
input_tokensintegerrequired
Total input (prompt) tokens in the bucket.
output_cost_usdnumberrequired
Total cost of output tokens in the bucket.
output_tokensintegerrequired
Total output (completion) tokens in the bucket.
period_startstringrequired
Start of the bucket in YYYY-MM-DD (UTC) — the day, the week start (Monday), or the month start, depending on granularity.
total_tokensintegerrequired
Total tokens in the bucket, including prompt-cache tokens.
401Requires authentication
403Forbidden
500Internal Server Error

Error handling

A 401 is returned: Requires authentication. A 403 is returned: Forbidden. A 500 is returned: Internal Server Error.