Account & Usage

Manage your account, check credit balance, monitor usage, and view logs via the Floodgate REST API

The Floodgate REST API allows you to manage your account programmatically. Using your Personal Access Token (PAT), you can check your credit balance, monitor daily quotas, review recent request logs, and check available models without needing to open the web dashboard.

Base URL & Authentication

All account management endpoints use the base URL:

https://floodgate.dev

To authenticate, include your Personal Access Token in the Authorization header:

Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>

You can generate a Personal Access Token from the Floodgate dashboard under Profile Page> Access Tokens.

---

Balance & Quota

Get Account Profile & Balance

Retrieve your current credit balance, lifetime usage, and account tier.

curl -s -X GET "https://floodgate.dev/api/user/self" \
  -H "Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>"

Quota Conversion

Floodgate measures balance in standard quota units:

• 500,000 units = $1.00 USD
• To convert quota units to USD: USD = quota / 500,000

Example Response

{
  "success": true,
  "message": "",
  "data": {
    "id": 255,
    "username": "developer",
    "group": "default",
    "quota": 15000000,
    "used_quota": 5420000,
    "request_count": 842,
    "status": 1
  }
}

• quota: Current remaining balance in quota units.
• used_quota: Total quota units consumed over the lifetime of the account.
• request_count: Total number of API requests processed.
• group: The pricing and rate-limit group assigned to your account.

---

Get Daily Quota Status

Check your daily spending limits, current daily spend, and when the limit resets.

curl -s -X GET "https://floodgate.dev/api/user/self/daily-quota" \
  -H "Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>"

Example Response

{
  "success": true,
  "message": "",
  "data": {
    "enabled": true,
    "limit_usd": 50.0,
    "used_usd": 12.35,
    "remaining_usd": 37.65,
    "reset_at": 1727481600,
    "model_limits_usd": {}
  }
}

• enabled: Whether daily quota limits are active for your group.
• limit_usd: Maximum allowed spend per day in USD.
• used_usd: USD spent during the current 24-hour cycle.
• remaining_usd: Remaining spending allowance before the next reset.
• reset_at: Unix timestamp when the daily limit resets (UTC).

---

Subscriptions

Get Active Subscriptions

Check active subscription tiers and billing preference.

curl -s -X GET "https://floodgate.dev/api/subscription/self" \
  -H "Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>"

Example Response

{
  "success": true,
  "message": "",
  "data": {
    "billing_preference": "subscription_first",
    "subscriptions": [
      {
        "id": 12,
        "plan_id": 3,
        "plan_name": "Pro Tier",
        "status": "active",
        "starts_at": 1725148800,
        "expires_at": 1727740800
      }
    ]
  }
}

---

Usage & Activity Logs

Get Request Logs

Retrieve a paginated history of your API calls, tokens consumed, latency, and cost per request.

curl -s -X GET "https://floodgate.dev/api/log/self?p=1&page_size=20&type=2" \
  -H "Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>"

Query Parameters

Parameter	Type	Default	Description
p	integer	1	Page number.
page_size	integer	20	Number of log items per page (e.g. 20 or 30).
type	integer	-	Filter by event type: 2 filters for inference consumption.
model_name	string	-	Filter by specific model (e.g. claude-opus-5-5).
start_timestamp	integer	-	Filter logs created after this Unix timestamp.
end_timestamp	integer	-	Filter logs created before this Unix timestamp.

Example Response

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 520,
    "items": [
      {
        "id": 1045,
        "created_at": 1727402940,
        "model_name": "claude-opus-5-5",
        "prompt_tokens": 1420,
        "completion_tokens": 280,
        "quota": 4500,
        "use_time": 3,
        "token_name": "production-key",
        "request_id": "20260927000851..."
      }
    ]
  }
}

• quota: Credits consumed by this specific request.
• prompt_tokens: Input tokens sent.
• completion_tokens: Output tokens generated.
• use_time: Request duration / latency in seconds.

---

Get Aggregate Usage Statistics

Get a quick aggregate summary of total quota consumed, average requests per minute (RPM), and tokens per minute (TPM).

curl -s -X GET "https://floodgate.dev/api/log/self/stat" \
  -H "Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>"

Example Response

{
  "success": true,
  "message": "",
  "data": {
    "quota": 5420000,
    "rpm": 14,
    "tpm": 18500
  }
}

---

Models & Top-Up History

List Available Models

Retrieve the list of model identifiers currently enabled for your user tier.

curl -s -X GET "https://floodgate.dev/api/user/models" \
  -H "Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>"

Example Response

{
  "success": true,
  "message": "",
  "data": [
    "claude-opus-5-5",
    "claude-fable-5-1",
    "gpt-6-sol",
    "gpt-6-astra",
    "grok-4.7"
  ]
}

---

View Top-Up History

View past credit recharges, redeemed vouchers, and payment records.

curl -s -X GET "https://floodgate.dev/api/user/topup/self?p=1&page_size=10" \
  -H "Authorization: Bearer <YOUR_PERSONAL_ACCESS_TOKEN>"

Example Response

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 10,
    "total": 3,
    "items": [
      {
        "id": 42,
        "created_time": 1726000000,
        "amount": 25.0,
        "quota": 12500000,
        "status": "success"
      }
    ]
  }
}