Usage API

Usage endpoints are available under

/api/v1/usage

GET

/api/v1/usage/current

Returns usage for the current billing period (requests, tokens, costs) plus best-effort rate limit status.

The response may include additional fields such as

endpoint_breakdown

and

cost_projection

.

{
  "success": true,
  "data": {
    "current_period": {
      "start_date": "2026-02-01T00:00:00Z",
      "end_date": "2026-03-01T00:00:00Z",
      "total_requests": 245,
      "successful_requests": 238,
      "failed_requests": 7,
      "total_tokens": 48500,
      "total_cost": 0.97,
      "videos_processed": 89
    },
    "rate_limits": {
      "requests_per_hour": {
        "limit": 100,
        "used": 23,
        "remaining": 77,
        "reset_at": "2026-02-14T12:00:00Z"
      }
    }
  },
  "meta": {
    "request_id": "req_1700000000.0",
    "timestamp": "2026-02-14T12:00:00Z",
    "version": "v1"
  }
}

GET

/api/v1/usage/history

Returns historical windowed usage for the authenticated key.

The response may include additional fields such as

query_info

.

{
  "success": true,
  "data": {
    "periods": [
      {
        "start_date": "2026-02-01T00:00:00Z",
        "end_date": "2026-02-02T00:00:00Z",
        "total_requests": 120,
        "successful_requests": 117,
        "failed_requests": 3,
        "total_tokens": 24000,
        "total_cost": 0.48,
        "videos_processed": 20
      }
    ],
    "summary": {
      "total_periods": 1,
      "total_requests": 120,
      "total_tokens": 24000,
      "total_cost": 0.48,
      "avg_requests_per_period": 120,
      "granularity": "daily"
    }
  },
  "meta": {
    "request_id": "req_1700000000.0",
    "timestamp": "2026-02-14T12:00:00Z",
    "version": "v1"
  }
}