# Get Balance

Check your account balance and available credits before launching operations

This endpoint returns your current account balance and credit information. Use it to check available credits before launching expensive scraping operations or to monitor your spending.

It's recommended to check your balance before starting large-scale data collection tasks to ensure you have sufficient credits.

## Headers

<ParamField header="Authorization" type="string" required>
  Your API authentication token. Value: `Token YOUR_API_KEY`
</ParamField>

<ParamField header="Content-Type" type="string" default="application/json">
  Content type of the request. Value: `application/json`
</ParamField>

## Response Field Explanations

<ResponseField name="id" type="string">
  The plan's price identifier. Example: `"price_abc123"`
</ResponseField>

<ResponseField name="object" type="string">
  Always `"plan"`.
</ResponseField>

<ResponseField name="name" type="string">
  Name of the active subscription plan. Example: `"Professional"`
</ResponseField>

<ResponseField name="available" type="integer">
  Total credits on the plan (including bonus). For daily-interval plans, this is the daily allowance. Example: `10000`
</ResponseField>

<ResponseField name="consumed" type="integer">
  Credits consumed in the current billing period. Example: `1550`
</ResponseField>

<ResponseField name="bonus_credit" type="integer">
  Bonus credits applied to the account. Example: `0`
</ResponseField>

<ResponseField name="rollover_credit" type="integer">
  Unused credits rolled over from a previous period. Example: `200`
</ResponseField>

<ResponseField name="rollover_credit_expires_at" type="string | null">
  Timestamp when rollover credits expire, or `null` if none. Example: `null`
</ResponseField>

<ResponseField name="interval" type="string">
  Credit reset interval (`"monthly"` or `"daily"`). Example: `"monthly"`
</ResponseField>

<ResponseField name="used_slots" type="integer">
  Slots used by your runs in progress right now: the `concurrency` of each `PENDING` or `RUNNING` run of an active squid, added up. Squids that are not running use none. Example: `3`
</ResponseField>

<ResponseField name="total_available_slots" type="integer">
  Slots on your plan: how many scrapers run at the same time across your squids. A launch that would go past them is refused with `SlotsLimitExceeded`. Example: `10`
</ResponseField>

<ResponseField name="squids" type="integer">
  Squids on your account, running or not. Example: `12`
</ResponseField>

<ResponseField name="max_squids" type="integer">
  Squids your plan holds: 100 per slot. Past it, creating a squid answers `SquidsLimitExceeded`. Example: `1000`
</ResponseField>

<ResponseField name="has_unpaid_bill" type="object">
  Outstanding unpaid invoice info. Empty object (`{}`) when there is no unpaid bill — despite the name, this is not a boolean. When a bill is outstanding it carries `status` (boolean) and `created_on` (Unix timestamp). Example: `{"status": true, "created_on": 1777545119}`
</ResponseField>

<ResponseField name="reset_time" type="string">
  Timestamp when credits will next reset. Example: `"2025-02-01T00:00:00Z"`
</ResponseField>

<Tip>
  Check your balance before launching expensive operations to avoid running out of credits mid-task. Large scraping jobs can consume significant credits.
</Tip>

<Note>
  Balance information is updated in real-time. Each successful API response reflects your current credit balance.
</Note>

<Warning>
  If your balance reaches zero, ongoing operations will be paused until you add more credits. Plan ahead to avoid service interruptions.
</Warning>

## Code Examples

<CodeGroup>
```bash cURL
curl -X GET "https://api.lobstr.io/v1/user/balance" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```python Python
import requests

headers = {
    "Authorization": "Token YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.get(
    "https://api.lobstr.io/v1/user/balance",
    headers=headers
)

balance_data = response.json()
print(f"Plan: {balance_data['name']}")
print(f"Total credits: {balance_data['available']}")
print(f"Consumed: {balance_data['consumed']}")
print(f"Remaining: {balance_data['available'] - balance_data['consumed']}")
print(f"Slots used: {balance_data['used_slots']} / {balance_data['total_available_slots']}")
```
</CodeGroup>

## Response

```json 200
{
  "id": "price_abc123",
  "object": "plan",
  "name": "Professional",
  "available": 10000,
  "consumed": 1550,
  "bonus_credit": 0,
  "rollover_credit": 200,
  "rollover_credit_expires_at": null,
  "interval": "monthly",
  "used_slots": 3,
  "total_available_slots": 10,
  "squids": 12,
  "max_squids": 1000,
  "has_unpaid_bill": {},
  "reset_time": "2025-02-01T00:00:00Z"
}
```
