> ## Documentation Index
> Fetch the complete documentation index at: https://parse-docs.pantherpulse.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

> Check your remaining page quota

# Usage

Check your current page usage and remaining quota for the billing period.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://parse.pantherpulse.ai/v1/usage \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  api_key = "YOUR_API_KEY"

  response = requests.get(
      "https://parse.pantherpulse.ai/v1/usage",
      headers={"Authorization": f"Bearer {api_key}"}
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const axios = require('axios');

  const response = await axios.get(
    'https://parse.pantherpulse.ai/v1/usage',
    {
      headers: { Authorization: 'Bearer YOUR_API_KEY' }
    }
  );
  console.log(response.data);
  ```
</RequestExample>

## Request

### Path

`GET /v1/usage`

### Headers

| Header        | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| Authorization | string | Yes      | Bearer token: `Bearer YOUR_API_KEY` |

## Response

<ResponseExample>
  ```json Success theme={null}
  {
    "current_month": "2025-10",
    "plan": "Professional",
    "pages_limit": 1000,
    "pages_used": 347,
    "pages_remaining": 653,
    "usage_percentage": 34.7,
    "reset_date": "2025-11-01T00:00:00Z",
    "month_started": "2025-10-01T00:00:00Z"
  }
  ```

  ```json Error - Invalid API Key theme={null}
  {
    "error": {
      "code": "invalid_api_key",
      "message": "Invalid API key"
    }
  }
  ```
</ResponseExample>

### Response Fields

| Field             | Type   | Description                                        |
| ----------------- | ------ | -------------------------------------------------- |
| current\_month    | string | Current billing month (YYYY-MM)                    |
| plan              | string | Your active plan (Starter, Professional, Business) |
| pages\_limit      | number | Total pages allowed this month                     |
| pages\_used       | number | Pages consumed so far this month                   |
| pages\_remaining  | number | Pages available to use                             |
| usage\_percentage | number | Percentage of quota used (0-100)                   |
| reset\_date       | string | ISO 8601 timestamp when quota resets               |
| month\_started    | string | ISO 8601 timestamp when billing month started      |

## Page Consumption

Pages are consumed when you successfully upload PDFs:

* Each page of the PDF = 1 page consumed
* Consumption happens on upload (even if processing fails later)
* Pages reset automatically at month start

## Examples

### Check Before Uploading

```python theme={null}
import requests

def safe_upload(files, api_key):
    # Check usage first
    usage = requests.get(
        'https://parse.pantherpulse.ai/v1/usage',
        headers={'Authorization': f'Bearer {api_key}'}
    ).json()
    
    total_pages = sum(get_page_count(f) for f in files)
    
    if total_pages > usage['pages_remaining']:
        print(f"Not enough quota. Need {total_pages}, have {usage['pages_remaining']}")
        return False
    
    # Safe to upload
    return upload_files(files, api_key)
```

### Monitor Usage Percentage

```python theme={null}
usage = requests.get(...).json()

if usage['usage_percentage'] > 80:
    print(f"⚠️  Warning: {usage['usage_percentage']}% quota used")
elif usage['usage_percentage'] > 95:
    print(f"🚨 Critical: {usage['usage_percentage']}% quota used")
```

## Quota Plans

| Plan         | Pages/Month | Monthly Cost |
| ------------ | ----------- | ------------ |
| Starter      | 250         | \$99         |
| Professional | 1,000       | \$299        |
| Business     | 3,500       | \$699        |

To upgrade, contact [support@pantherpulse.ai](mailto:support@pantherpulse.ai) or visit your dashboard.

## FAQ

**Q: When do pages reset?**\
A: On the 1st of each calendar month at 00:00 UTC.

**Q: What if I exceed my quota?**\
A: Uploads will be rejected with a `limit_exceeded` error. Upgrade your plan to continue.

**Q: Can I carry over unused pages?**\
A: No, pages don't roll over. They reset each month.

**Q: What counts as a page?**\
A: Each physical page of the PDF file uploaded. A 10-page statement = 10 pages consumed.