The Trinity Beast – LRS Report Management Guide

1. Overview

The Listener Report Service (LRS) provides four report endpoints that give you visibility into your API usage and report generation history. Every subscription tier includes LRS access — the difference is how many reports you can generate per month.

All four endpoints count against the same monthly and daily report limits. Every report request — whether it's a usage detail, usage summary, report-usage detail, or report-summary — uses one report from your monthly allowance.

2. Report Limits by Tier

Monthly counts reset automatically on the first day of each calendar month via the nightly sync job. There is no daily limit — you can use all your reports in a single day or spread them across the month. It's your choice.

3. LRS Add-On — Unlimited Reports

After purchasing the add-on through Stripe, your API key is automatically upgraded. No configuration changes needed — your next report request will have unlimited access.

4. LRS Report Endpoints

All endpoints require authentication via Authorization: Bearer YOUR_API_KEY header or api_key_id query parameter. All endpoints support four output formats (json, csv, tsv, text).

4.1 GET /reports/usage — API Usage Detail

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://lrs.cpmp-site.org/reports/usage?asset=BTC&start_date=2026-03-01&page_size=50"

4.2 GET /reports/summary — API Usage Summary

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://lrs.cpmp-site.org/reports/summary?start_date=2026-03-01"

4.3 GET /reports/report-usage — Report History Detail

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://lrs.cpmp-site.org/reports/report-usage?report_type=usage&page_size=20"

4.4 GET /reports/report-summary — Report History Summary

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://lrs.cpmp-site.org/reports/report-summary?start_date=2026-03-01"

5. Output Formats

All four report endpoints support the same four output formats. Use the format query parameter to select your preferred format.

6. Date Range Rules

All report endpoints enforce consistent date range validation:

7. Error Responses

All LRS error responses are returned as structured JSON with a consistent format, regardless of the requested output format. Every error message includes the 🛑 indicator, the region, cluster node, HTTP status code, and a complete sentence describing the issue.

Error Response Format

{
  "error": "🛑 [LRS] [us-east-2] [BeastMirror] [400] Invalid date format for start_date parameter.",
  "code": 400,
  "service": "LRS",
  "region": "us-east-2",
  "cluster_node": "BeastMirror",
  "timestamp": "2026-05-03T18:30:00Z"
}

Status Indicators & Graduated Usage Warnings

Every LRS response includes a status field and, when usage is elevated, a usage_warning field. The warning thresholds are runtime-tunable via application parameters (default: 85% / 90% / 95%).

Plain-Text Response Format

By default, all LRS responses use the emoji status indicators shown above — the Trinity Beast Convention (TBC) format. If your system does not render emoji well, or you prefer machine-friendly text-only responses, you can request plain-text mode by submitting a support ticket through our Support page.

Once enabled for your API key, all status indicators switch to text equivalents:

Error Codes

429 — Limit Exceeded Response

When your report limit is exceeded, the response includes your API key, current usage, your limit, usage percentage, the graduated warning level, a link to upgrade, and which server caught the limit:

{
  "error": "🛑 [LRS] [us-east-2] [BeastLRS] [429] Monthly report limit exceeded",
  "code": 429,
  "status": "🛑🔴",
  "service": "LRS",
  "region": "us-east-2",
  "cluster_node": "BeastLRS",
  "timestamp": "2026-05-03T18:30:00Z",
  "api_key_id": "key_abc123",
  "monthly_usage": 10,
  "monthly_limit": 10,
  "usage_pct": 100,
  "usage_warning": "red",
  "upgrade_url": "https://cpmp-site.org/subscribe#lrs-addon"
}

8. Response Examples

Every LRS JSON response includes status, monthly_usage, monthly_limit, usage_pct, tier, and — when usage is elevated — usage_warning. These fields mirror the graduated warning system used by the LPO price API.

8.1 Usage Detail — Success Response (Normal)

Example request: GET /reports/usage?asset=BTC&start_date=2026-04-01&page_size=2

{
  "status": "✅",
  "logs": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
      "api_key_id": "key_abc123",
      "asset": "BTC",
      "price": 94250.12,
      "source": "coinbase",
      "cached": false,
      "latency_ms": 0,
      "duration_ms": 2,
      "ip_address": "203.0.113.42",
      "timestamp": 1714761600,
      "readable_timestamp": "2026-05-03T12:00:00Z",
      "cache_age_seconds": 0,
      "region": "us-east-2",
      "cluster_node": "BeastMain"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
      "api_key_id": "key_abc123",
      "asset": "BTC",
      "price": 94248.75,
      "source": "gemini",
      "cached": true,
      "latency_ms": 0,
      "duration_ms": 1,
      "ip_address": "203.0.113.42",
      "timestamp": 1714761300,
      "readable_timestamp": "2026-05-03T11:55:00Z",
      "cache_age_seconds": 2.4,
      "region": "us-east-2",
      "cluster_node": "BeastMirror"
    }
  ],
  "total_count": 247,
  "page": 1,
  "page_size": 2,
  "filters": {
    "api_key_id": "key_abc123",
    "asset": "BTC",
    "start_date": "2026-04-01"
  },
  "monthly_usage": 3,
  "monthly_limit": 10,
  "usage_pct": 30,
  "tier": "pro"
}

8.2 Usage Summary — Success Response (Normal)

Example request: GET /reports/summary?start_date=2026-04-01

{
  "status": "✅",
  "total_requests": 1482,
  "cache_hit_rate": 87.45,
  "avg_latency_ms": 1.23,
  "by_asset": {
    "BTC": 612,
    "ETH": 445,
    "SOL": 218,
    "XRP": 207
  },
  "by_source": {
    "coinbase": 520,
    "gemini": 380,
    "kraken": 310,
    "bybit": 272
  },
  "date_range": {
    "start": "2026-04-01",
    "end": "2026-05-03"
  },
  "monthly_usage": 4,
  "monthly_limit": 10,
  "usage_pct": 40,
  "tier": "pro"
}

8.3 Report-Usage Detail — Success Response

Example request: GET /reports/report-usage?start_date=2026-03-16&end_date=2026-04-15&report_type=usage&format=json

{
  "status": "✅",
  "logs": [
    {
      "id": "f7a1b2c3-d4e5-6789-abcd-ef0123456789",
      "api_key_id": "key_abc123",
      "report_type": "usage",
      "report_run_date": "2026-04-15T10:30:00Z",
      "asset_filter": "BTC",
      "start_date_filter": "2026-03-15",
      "end_date_filter": "2026-04-15",
      "max_rows_returned": "247",
      "report_duration_ms": "42",
      "output_format": "json",
      "region": "us-east-2",
      "cluster_node": "BeastMirror"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
      "api_key_id": "key_abc123",
      "report_type": "usage",
      "report_run_date": "2026-04-12T08:15:00Z",
      "asset_filter": "ETH",
      "start_date_filter": "2026-04-01",
      "end_date_filter": "2026-04-12",
      "max_rows_returned": "89",
      "report_duration_ms": "28",
      "output_format": "csv",
      "region": "us-east-2",
      "cluster_node": "BeastLRS"
    }
  ],
  "total_count": 2,
  "page": 1,
  "page_size": 100,
  "monthly_usage": 5,
  "monthly_limit": 10,
  "usage_pct": 50,
  "tier": "pro"
}

8.4 Report-Summary — Success Response

Example request: GET /reports/report-summary?start_date=2026-03-16&end_date=2026-04-15&format=json

{
  "status": "✅",
  "total_reports": 7,
  "by_report_type": {
    "usage": 4,
    "summary": 2,
    "report-usage": 1
  },
  "by_output_format": {
    "json": 5,
    "csv": 1,
    "text": 1
  },
  "by_cluster_node": {
    "BeastMirror": 5,
    "BeastLRS": 2
  },
  "avg_duration_ms": 38.71,
  "avg_rows_returned": 2145.86,
  "date_range": {
    "start": "2026-03-16",
    "end": "2026-04-15"
  },
  "monthly_usage": 6,
  "monthly_limit": 10,
  "usage_pct": 60,
  "tier": "pro"
}

Report-Summary (Text)

LRS Report Summary — 2026-03-16 to 2026-04-15
============================================================
Total Reports     : 7
Avg Duration      : 38.71ms
Avg Rows Returned : 2145.86

By Report Type:
  usage            4
  summary          2
  report-usage     1

By Output Format:
  json         5
  csv          1
  text         1

By Cluster Node:
  BeastMirror  5
  BeastLRS     2

8.5 Graduated Warning Examples (All Levels)

As your monthly report usage increases, the status and usage_warning fields change to give you advance notice before hitting your limit. These examples show the metadata fields at each warning level for a Pro tier subscriber with a 10-report monthly limit.

Normal — Below 85% (8 of 10 used)

// 8 of 10 reports used = 80% — below green threshold
{
  "status": "✅",
  ...
  "monthly_usage": 8,
  "monthly_limit": 10,
  "usage_pct": 80,
  "tier": "pro"
  // No usage_warning field — usage is within normal range
}

🟡 Green Warning — At or Above 85% (9 of 10 used)

// 9 of 10 reports used = 90% — above green AND yellow thresholds
{
  "status": "✅⚠️",
  ...
  "monthly_usage": 9,
  "monthly_limit": 10,
  "usage_pct": 90,
  "usage_warning": "yellow",
  "tier": "pro"
}

⚠️ Yellow Warning — At or Above 90%

Shown above at 9 of 10 (90%). For subscribers with higher limits, here's what yellow looks like:

// Enterprise subscriber with 50-report limit, 46 used = 92%
{
  "status": "✅⚠️",
  ...
  "monthly_usage": 46,
  "monthly_limit": 50,
  "usage_pct": 92,
  "usage_warning": "yellow",
  "tier": "enterprise"
}

🔴 Red Warning — At or Above 95%

// Enterprise subscriber with 50-report limit, 48 used = 96%
{
  "status": "✅🔴",
  ...
  "monthly_usage": 48,
  "monthly_limit": 50,
  "usage_pct": 96,
  "usage_warning": "red",
  "tier": "enterprise"
}

8.6 Limit Exceeded (429)

When your monthly report limit is reached, the LRS returns a 429 with full usage context and a link to upgrade:

{
  "error": "🛑 [LRS] [us-east-2] [BeastLRS] [429] Monthly report limit exceeded",
  "code": 429,
  "status": "🛑🔴",
  "service": "LRS",
  "region": "us-east-2",
  "cluster_node": "BeastLRS",
  "timestamp": "2026-05-03T18:30:00Z",
  "api_key_id": "key_abc123",
  "monthly_usage": 10,
  "monthly_limit": 10,
  "usage_pct": 100,
  "usage_warning": "red",
  "upgrade_url": "https://cpmp-site.org/subscribe#lrs-addon"
}

8.7 Exempt Tier Response (Unlimited / Lifetime / LRS Add-On)

Subscribers on Unlimited, Lifetime, or with the LRS add-on see unlimited access with zeroed limits:

{
  "status": "✅",
  "total_reports": 42,
  "by_report_type": {
    "usage": 20,
    "summary": 12,
    "report-usage": 6,
    "report-summary": 4
  },
  "by_output_format": {
    "json": 30,
    "csv": 8,
    "tsv": 2,
    "text": 2
  },
  "by_cluster_node": {
    "BeastMain": 18,
    "BeastMirror": 14,
    "BeastLRS": 10
  },
  "avg_duration_ms": 31.45,
  "avg_rows_returned": 1876.33,
  "date_range": {
    "start": "2026-04-01",
    "end": "2026-05-03"
  },
  "monthly_usage": 0,
  "monthly_limit": 0,
  "usage_pct": 0,
  "tier": "unlimited"
}