Agencies
What an API key from an agency workspace can reach, and how to read your clients' monthly usage.
An agency manages client workspaces from its own agency workspace. API keys follow that separation strictly.
What an agency key reaches
A key created in an agency workspace works inside the agency workspace only. It cannot open, read or change a client workspace. There is no way to make a key act inside a client.
If an integration has to work inside a client workspace, a workspace admin of that client creates a key there.
Read client usage
One thing an agency key can read about its clients is their monthly usage, for reporting or billing. This needs the agency-usage:read scope, which exists only in agency workspaces, and the person behind the key must be an agency admin.
curl "$AGENTWORKS_API_URL/agency/clients/$CLIENT_ID/usage?month=2026-09" \
-H "Authorization: Bearer $AGENTWORKS_API_KEY"
{
"client_id": "…",
"month": "2026-09",
"agents": [
{ "agent_id": "…", "name": "Invoice checker", "runs": 42, "failed_runs": 1, "tokens_in": 310000, "tokens_out": 18000, "cost_eur": 3.21 }
],
"total_runs": 42,
"total_tokens_in": 310000,
"total_tokens_out": 18000,
"total_cost_eur": 3.21
}
month is a calendar month in UTC, written YYYY-MM. Leave it out for the current month.
The scope reaches this one endpoint. Other agency functions — clients, distribution, billing — are done in the agency console.