User and Billing Management

GET /v1/user

Retrieve basic user details including pricing tier, maximum allowed sessions, active sessions and available balance.

Response Example:

json
{
  "success": true,
  "user_name": "happy-panda",
  "email": "[email protected]",
  "max_sessions": 2,
  "active_sessions": 0,
  "balance": 15.50,
  "pricing_tier": "basic",
  "total_billed": 12.00
}

GET /v1/transactions

Retrieve a paginated list of transaction history (ordered by creation date, newest first). This includes deposits, refunds and promo codes applied to the account.

Query Parameters:

• limit (integer, optional): Maximum number of transactions to return. Maximum 50, Default 10.
• offset (integer, optional): Pagination offset. Default 0.

Response Example:

json
{
  "success": true,
  "transactions": [
    {
      "transaction_id": "tx_123456789",
      "amount": 20.00,
      "currency": "USD",
      "payment_method": "stripe",
      "status": "succeeded",
      "type": "deposit",
      "created_at": "2026-12-01T10:00:00Z"
    }
  ]
}

POST /v1/billing/topup

Generate a Stripe Checkout Session URL to top up the user's balance.

Request Body (JSON):

• amount (float, required): The amount in USD to top up. Minimum is $1.00.

Request Example:

bash
curl -X POST https://api.getbro.ws/v1/billing/topup \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.0
  }'

Response Example:

json
{
  "success": true,
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_..."
}

GET /v1/billing/history

Retrieve a paginated history of session billing documents. This provides detailed breakdowns of how your balance was consumed by past and active sessions (ordered by creation date, newest first).

Query Parameters:

• limit (integer, optional): Maximum number of billing records to return. Maximum 50, Default 10.
• offset (integer, optional): Pagination offset. Default 0.

Response Example:

json
{
  "success": true,
  "history": [
    {
      "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
      "created_at": "2026-05-14T09:00:00Z",
      "last_synced_at": "2026-05-14T09:15:00Z",
      "total_cost": 0.04,
      "total_billed": 0.05,
      "breakdown": {
        "runner_billed": 0.01,
        "proxy_billed": 0.02,
        "grounding_billed": 0.01,
        "llm_billed": 0.01,
        "ocr_billed": 0.00
      },
      "proxy_usage": {
        "total_traffic_mb": 1.5
      },
      "tokens_usage": {
        "total": 1500,
        "prompt": 1000,
        "completion": 500
      }
    }
  ]
}