Account & Usage

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"
      }
    ]
  }
}

Getting Started

Coding Agents

API Reference

Base URL & Authentication

Balance & Quota

Get Account Profile & Balance

Quota Conversion

Example Response

Get Daily Quota Status

Example Response

Subscriptions

Get Active Subscriptions

Example Response

Usage & Activity Logs

Get Request Logs

Query Parameters

Example Response

Get Aggregate Usage Statistics

Example Response

Models & Top-Up History

List Available Models

Example Response

View Top-Up History

Example Response

​Base URL & Authentication

​Balance & Quota

​Get Account Profile & Balance

​Quota Conversion

​Example Response

​Get Daily Quota Status

​Example Response

​Subscriptions

​Get Active Subscriptions

​Example Response

​Usage & Activity Logs

​Get Request Logs

​Query Parameters

​Example Response

​Get Aggregate Usage Statistics

​Example Response

​Models & Top-Up History

​List Available Models

​Example Response

​View Top-Up History

​Example Response

Base URL & Authentication

Balance & Quota

Get Account Profile & Balance

Quota Conversion

Example Response

Get Daily Quota Status

Example Response

Subscriptions

Get Active Subscriptions

Example Response

Usage & Activity Logs

Get Request Logs

Query Parameters

Example Response

Get Aggregate Usage Statistics

Example Response

Models & Top-Up History

List Available Models

Example Response

View Top-Up History

Example Response