Usage

Query usage metering and tier status. All endpoints require authentication.

List daily usage records

GET /v1/usage

Returns paginated daily usage records for the authenticated account.

Query parameters

Parameter	Type	Default	Description
start_date	string	--	Filter from date (YYYY-MM-DD)
end_date	string	--	Filter to date (YYYY-MM-DD)
limit	integer	20	Items per page (max 100)
offset	integer	0	Pagination offset (max 10000)

Example

curl "https://api.zyntem.dev/v1/usage?start_date=2026-03-01&end_date=2026-03-31" \
  -H "Authorization: Bearer zyn_test_abc123def456..."

Response 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "account_id": "9f8e7d6c-5b4a-3210-fedc-ba0987654321",
      "date": "2026-03-22",
      "transaction_count": 142,
      "deployment_mode": "hosted",
      "agent_count": 0,
      "reported_to_stripe": true,
      "created_at": "2026-03-23T01:00:00Z"
    }
  ],
  "total": 22,
  "limit": 20,
  "offset": 0
}

---

Get tier status

GET /v1/usage/tier

Returns the current rate-limit tier and a recommendation for whether it should change.

Example

curl https://api.zyntem.dev/v1/usage/tier \
  -H "Authorization: Bearer zyn_test_abc123def456..."

Response 200 OK

{
  "account_id": "9f8e7d6c-5b4a-3210-fedc-ba0987654321",
  "current_tier": "growth",
  "rolling_avg_daily_transactions": 142.5,
  "recommended_tier": "scale",
  "would_upgrade": true
}

---

Trigger usage aggregation (Admin)

POST /v1/admin/usage/aggregate

Manually triggers the daily usage aggregation job. Aggregates transaction counts, reports to Stripe, and evaluates tier upgrades.

Request body

Field	Type	Required	Description
date	string	No	Date to aggregate (YYYY-MM-DD). Defaults to yesterday.

Example

curl -X POST https://api.zyntem.dev/v1/admin/usage/aggregate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zyn_live_admin_key..." \
  -d '{"date": "2026-03-22"}'

Response 200 OK

{
  "date": "2026-03-22",
  "accounts_processed": 45,
  "total_transactions": 12340,
  "stripe_reported": 42,
  "stripe_failed": 0,
  "tier_upgrades": 2,
  "duration_ms": 3450
}