Usage API

The Usage API provides an audit trail of file processing with per-file credit consumption. All endpoints require Clerk JWT authentication.

---

List Usage Records

GET /usage/

Returns paginated usage records for the authenticated user, ordered by most recent first.

Query parameters:

Param	Type	Default
skip	integer	0
limit	integer	20 (max 100)

curl -H "Authorization: Bearer TOKEN" \
  "https://api.excellent-banking.com/usage/?limit=10"

Response (200):

[
  {
    "id": 89,
    "file_id": 128,
    "file_size": 1048576,
    "total_characters": 4500,
    "total_pages": 3,
    "credits_consumed": 3,
    "created_at": "2026-05-09T10:32:00Z"
  },
  {
    "id": 88,
    "file_id": 127,
    "file_size": 768000,
    "total_characters": 2800,
    "total_pages": 2,
    "credits_consumed": 2,
    "created_at": "2026-05-08T14:20:00Z"
  }
]

Note: file_id does not have a foreign key constraint — records persist even after the associated file is deleted, preserving your billing audit trail.

---

Usage Summary

GET /usage/summary

Returns aggregated statistics across all processed files.

curl -H "Authorization: Bearer TOKEN" \
  https://api.excellent-banking.com/usage/summary

Response (200):

{
  "total_files": 12,
  "total_characters": 48500,
  "total_pages": 34,
  "total_file_size": 10485760
}

Field	Description
total_files	Total number of files ever processed
total_characters	Sum of characters extracted across all files
total_pages	Sum of pages across all files
total_file_size	Sum of raw file sizes in bytes