Reporting Overview

Use this page to understand the reporting surface, when to use the read APIs, and when to generate a frozen export instead.

Who This Is For

operators monitoring usage, audit evidence, and settlement inputs
developers wiring reporting into internal tools
teams that need a stable reporting API separate from dashboard screens

When To Use This

Read this page when you need reporting behavior rather than core runtime licensing behavior.

If you only need health counters or webhook queue summaries, the ops endpoints may be enough. If you need usage evidence, customer rollups, or export artifacts, use the reporting surface described here.

How It Works

Reporting center of gravity

The reporting surface is designed around:

visibility
controls
evidence

It is not a billing engine. It gives you reporting reads and frozen export artifacts built from stored reporting data.

Auth model

Reporting uses bearer-auth management routes with two distinct scopes:

report:read for read APIs
report:export for export creation, metadata lookup, and artifact download

admin also satisfies both.

Read APIs

Current reporting reads:

Endpoint	Scope	Use it for
`GET /api/v1/activities`	`report:read`	normalized activity feed across usage, lifecycle, and other reporting events
`GET /api/v1/reports/usage-summary`	`report:read`	grouped usage totals
`GET /api/v1/reports/usage-ledger`	`report:read`	row-level usage history
`GET /api/v1/reports/license-audit`	`report:read`	license-centric audit and evidence view
`GET /api/v1/reports/customer-summary`	`report:read`	customer-level rollups
`GET /api/v1/reports/subscription-settlement`	`report:read`	subscription or order settlement-oriented summaries

Common query model

Depending on the endpoint, the reporting surface supports a shared vocabulary of filters such as:

from
to
product_id
customer_id
license_id
order_id
subscription_id
feature_code
limit

Ledger-like endpoints also use cursor pagination where appropriate.

Read API vs export API

Use read APIs when you need:

interactive filters
internal dashboards
drill-down exploration
near-term operational or financial analysis

Use exports when you need:

a frozen artifact
downloadable JSON, CSV, or PDF
stable handoff to another team or system
an auditable snapshot that should not change if live data changes later

Example

Read the activity feed for one customer:

bash

curl "https://api.licensekit.dev/api/v1/activities?customer_id=cust_123&limit=50" \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN"

Read grouped usage totals for one feature:

bash

curl "https://api.licensekit.dev/api/v1/reports/usage-summary?feature_code=api_calls&group_by=product_id" \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN"

Minimal export workflow:

POST /api/v1/reports/exports
GET /api/v1/reports/exports/{id}
GET /api/v1/reports/exports/{id}/download

Common Mistakes

using ops rollups as a substitute for reporting evidence
assuming read APIs return frozen artifacts
requesting export scope when the workflow only needs report reads
describing reporting as a pricing engine instead of an evidence and export layer

Reporting Overview ​

Who This Is For ​

When To Use This ​

How It Works ​

Reporting center of gravity ​

Auth model ​

Read APIs ​

Common query model ​

Read API vs export API ​

Example ​

Common Mistakes ​

Related Pages ​