Skip to main content
The usage reports plugin adds a Usage Analytics admin page with sortable Models and Users tables, preset and custom date ranges, and request, token, and cost totals.

Install

Each report is one aggregate call, so the database groups and sums the usage rows and none are loaded into memory. It works the same on FrogBot’s SQL and MongoDB adapters.

Admin tools

The plugin extends the usage-log collection with:
  • Grouped list views
  • A Usage Analytics view with date-range filtering and models/users breakdown tables
The Usage Analytics page contains aggregated totals. To also export filtered raw usage rows as CSV, add @frogbotai/plugin-import-export yourself and point it at the usage collection:

Report API

Authenticated callers can request aggregated data directly:
groupBy accepts model, user, or day. apiKey is also accepted when @frogbotai/plugin-api-keys is installed, in any order, or when the usage collection has an apiKey relationship. Other values return 400. The endpoint allows any authenticated caller by default, matching FrogBot’s default access. Pass access to narrow it with an ordinary access function. Returning false forbids the request; returning a Where restricts the rows the report reads:
Because allow() returns an access function, the roles plugin composes here without being a dependency:

Retention

Usage rows are kept indefinitely by default. Set retention to delete old rows on a schedule:
The task is frogbot-prune-<usage collection slug>.
  • Schedule. It runs at midnight daily unless you set cron. It is scheduled on the default queue, so a jobs runner that covers default prunes without extra setup.
  • Each run deletes rows whose requestedAt is older than days, 100 at a time, and fails the job if any row can’t be deleted.
Nothing is rolled up before rows are deleted. Reports for ranges older than the window return fewer rows or none, and an API key’s Total Cost (USD) covers only the kept rows. Leave retention off, or set a long window, if you need longer history.

Options