Togul meters flag evaluation counts per environment and surfaces them as time-bucketed rollups. Use the usage API to track consumption against your plan’s monthly evaluation quota.
How usage metering works
Every call to POST /api/v1/evaluate is counted against the organization’s monthly evaluation quota, scoped to the environment the evaluation runs in. Evaluations are recorded and aggregated into hourly and daily rollups.
When your organization exceeds the monthly evaluation quota, the evaluation endpoint returns 403 Forbidden until the quota resets at the start of the next billing period.
Exceeding your monthly evaluation quota blocks all flag evaluations with a 403 response. Monitor your usage regularly and upgrade your plan before hitting the limit.
List usage rollups
Returns all usage rollup records for the current organization.
GET /api/v1/usage — requires usage.read permission.
curl http://localhost:8080/api/v1/usage \
-H "Authorization: Bearer $TOKEN"
{
"usage": [
{
"metric": "evaluations",
"environment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"period_start": "2026-03-21T14:00:00Z",
"period_granularity": "hour",
"count": 4821
},
{
"metric": "evaluations",
"environment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"period_start": "2026-03-21T00:00:00Z",
"period_granularity": "day",
"count": 38450
}
]
}
UsageRollup schema
| Field | Type | Description |
|---|
metric | string | The measured metric (e.g., evaluations) |
environment_id | UUID | null | The environment the evaluations ran in; null for org-wide aggregates |
period_start | datetime | Start of the rollup window |
period_granularity | string | hour for hourly rollups, day for daily rollups |
count | integer | Number of evaluations in the period |
Monitoring your quota
To estimate remaining quota for the month, sum the count values for all day granularity records since the start of your current billing period (visible in current_period_start on your subscription).
If your usage is approaching the monthly_evaluations limit in your plan’s limits, consider upgrading your plan before the quota is exhausted.