Reporting Exports

Use this page to create, inspect, and download frozen reporting artifacts.

Who This Is For

• operators who need an auditable snapshot of reporting data
• developers building export workflows into internal systems
• teams handing reports to finance, support, or compliance reviewers

When To Use This

Use exports when a live query is not enough.

Choose the export API when you need a durable artifact that should stay stable even if live reporting data changes later.

How It Works

Export routes

Endpoint	Scope	Purpose
POST /api/v1/reports/exports	report:export	create a frozen report export
GET /api/v1/reports/exports/{id}	report:export	fetch export metadata
GET /api/v1/reports/exports/{id}/download	report:export	download the stored artifact

Report kinds

Current exportable report kinds are:

• usage-summary
• usage-ledger
• license-audit
• customer-summary
• subscription-settlement

Formats

The export API supports:

• json
• csv
• pdf

Create request

Minimal request shape:

{
  "report_kind": "usage-summary"
}

Optional fields:

• format
• filters

Metadata shape

Export metadata includes:

• id
• report_kind
• format
• status
• filters
• digest
• artifact_digest
• content_type
• created_by
• created_at
• updated_at
• download_url

These fields let callers track the export lifecycle and verify they are downloading the expected artifact.

Download behavior

The download route returns the stored artifact in the content type that matches the export format:

• application/json
• text/csv
• application/pdf

Use the metadata endpoint first if you need to inspect status or confirm the artifact type before downloading.

Example

Create a frozen usage summary export as CSV:

curl -X POST https://api.licensekit.dev/api/v1/reports/exports \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "report_kind": "usage-summary",
    "format": "csv",
    "filters": {
      "from": "2026-04-01T00:00:00Z",
      "to": "2026-05-01T00:00:00Z",
      "product_id": "prod_123"
    }
  }'

Typical metadata response fields:

{
  "data": {
    "id": "rptx_123",
    "report_kind": "usage-summary",
    "format": "csv",
    "status": "ready",
    "content_type": "text/csv",
    "digest": "sha256:...",
    "artifact_digest": "sha256:...",
    "download_url": "/api/v1/reports/exports/rptx_123/download"
  }
}

Download it:

curl -L https://api.licensekit.dev/api/v1/reports/exports/rptx_123/download \
  -H "Authorization: Bearer $LICENSEKIT_TOKEN"

Common Mistakes

• using report:read for export creation or download
• assuming a downloaded export is a live query result
• skipping the metadata lookup when you need to confirm format, digest, or status
• treating CSV or PDF as the only canonical representation of the export

Related Pages

• Reporting Overview
• API Reference
• Auth And Scopes