Usage reports

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

pnpm add @frogbotai/plugin-usage-reports

import { usageReportsPlugin } from '@frogbotai/plugin-usage-reports'
import { buildConfig } from 'frogbot'

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: databaseAdapter,
  collections: [{ slug: 'users', auth: true, fields: [] }],
  ai: {
    providers: {
      openai: { apiKey: process.env.OPENAI_API_KEY },
    },
  },
  plugins: [usageReportsPlugin()],
})

Reports use paginated local reads and in-memory reduction. They do not access Drizzle or another database adapter directly, so the same implementation supports 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:

import { importExportPlugin } from '@frogbotai/plugin-import-export'

plugins: [
  usageReportsPlugin(),
  importExportPlugin({
    collections: [{ slug: 'usage-logs', import: false, export: { format: 'csv' } }],
  }),
]

Report API

Authenticated callers can request aggregated data directly:

GET /api/usage/report?groupBy=model&from=2026-07-01T00:00:00.000Z&to=2026-08-01T00:00:00.000Z

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:

usageReportsPlugin({
  access: ({ req }) => (req.user?.isAdmin ? true : { user: { equals: req.user!.id } }),
})

Because allow() returns an access function, the roles plugin composes here without being a dependency:

import { allow } from '@frogbotai/plugin-roles'

usageReportsPlugin({ access: allow('admin', 'finance', 'auditor') })

Options

Option	Type	Default	Description
`pageSize`	`number`	`5000`	Number of usage rows read per page during report generation. Must be a positive integer.
`access`	`Access`	Authenticated users	Access function gating the report endpoint. Return `false` to forbid the request or a `Where` to restrict the rows it reads.

Large date ranges scan every matching usage row. Add rollups only after deployment profiling demonstrates that this portable path is insufficient.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Install

Admin tools

Report API

Options

​Install

​Admin tools

​Report API

​Options

Install

Admin tools

Report API

Options