# Usage

> Check your workspace credit balance and rate limit status.

## Introduction

The Usage endpoint returns your current workspace credit balance and rate limit status. Use it to monitor your consumption, check remaining credits, and verify rate limit windows, all **without spending any credits**.

Unlike the other V2 endpoints, this route uses `GET` and does not require a request body: send an authenticated request and read the `quotas` block in the response.

## Authorization

| Name     | Type   | Required | Description                                                                                         |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `apikey` | string | Yes      | Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header. |

## Response structure

| Field     | Type    | Description                                                                                  |
| --------- | ------- | -------------------------------------------------------------------------------------------- |
| `success` | boolean | `true` if the request was processed successfully                                             |
| `data`    | `null`  | Always `null` for this endpoint - all useful information lives in the `quotas` block below   |
| `error`   | `null`  | Always `null` on success                                                                     |

**quotas** (V2QuotaInfo): Credits and rate limit usage for your workspace and API key

| Field             | Type   | Description                                                         |
| ----------------- | ------ | ------------------------------------------------------------------- |
| `creditsConsumed` | number | Credits consumed by this request. Always `0` for the Usage endpoint |

**workspace** (Workspace): Workspace-level limits

| Field                 | Type    | Description                                    |
| --------------------- | ------- | ---------------------------------------------- |
| `id`                  | string  | Your workspace identifier                      |
| `hasUnlimitedCredits` | boolean | Whether workspace credits are unlimited        |
| `allowDailyOvercost`  | boolean | Whether the workspace may exceed its daily cap |

**credits** (Credits): Credit balance

| Field   | Type   | Description                |
| ------- | ------ | -------------------------- |
| `total` | number | Total credits in your plan |
| `used`  | number | Credits consumed so far    |
| `left`  | number | Remaining credits          |

**dailyLimit** (DailyLimit): Daily request limit (`null` if not configured)

| Field       | Type   | Description                             |
| ----------- | ------ | --------------------------------------- |
| `limit`     | number | Maximum requests per day                |
| `used`      | number | Requests made today                     |
| `left`      | number | Remaining requests today                |
| `nextReset` | string | When the daily window resets (ISO 8601) |

**minuteRateLimit** (MinuteRateLimit): Per-minute rate limit

| Field       | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| `limit`     | number | Maximum requests per minute              |
| `used`      | number | Requests made in the current minute      |
| `left`      | number | Remaining requests in the current minute |
| `nextReset` | string | When the minute window resets (ISO 8601) |

**key** (ApiKey): API key-level limits (`null` when request is from dashboard)

| Field | Type   | Description        |
| ----- | ------ | ------------------ |
| `id`  | string | API key identifier |

**dailyLimit** (KeyDailyLimit): Daily limit for this key (`null` if not configured)

| Field       | Type   | Description                             |
| ----------- | ------ | --------------------------------------- |
| `limit`     | number | Maximum requests per day                |
| `used`      | number | Requests made today                     |
| `left`      | number | Remaining requests today                |
| `nextReset` | string | When the daily window resets (ISO 8601) |

**minuteRateLimit** (KeyMinuteRateLimit): Minute rate limit for this key

| Field       | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| `limit`     | number | Maximum requests per minute              |
| `used`      | number | Requests made in the current minute      |
| `left`      | number | Remaining requests in the current minute |
| `nextReset` | string | When the minute window resets (ISO 8601) |

**metadata** (V2ResponseMetadata): Request tracking information

| Field             | Type   | Description                          |
| ----------------- | ------ | ------------------------------------ |
| `requestId`       | string | Unique identifier for this request   |
| `executionTimeMs` | number | Total execution time in milliseconds |

## Code examples

**Code Examples**

```bash [cURL]
curl https://api.reversecontact.com/v2/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```javascript [JavaScript]
const response = await fetch("https://api.reversecontact.com/v2/usage", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});

const data = await response.json();
console.log("Credits left:", data.quotas.workspace.credits.left);
console.log("Rate limit:", data.quotas.workspace.minuteRateLimit.left, "requests remaining");
```
```python [Python]
import requests

response = requests.get(
    "https://api.reversecontact.com/v2/usage",
    headers={
        "Authorization": "Bearer YOUR_API_KEY"
    }
)

data = response.json()
print("Credits left:", data["quotas"]["workspace"]["credits"]["left"])
print("Rate limit:", data["quotas"]["workspace"]["minuteRateLimit"]["left"], "requests remaining")
```

## Example response

**Example Response**

```json [200 - Success]
{
  "success": true,
  "data": null,
  "error": null,
  "metadata": {
    "requestId": "req_u1s2a3g4e5f6",
    "executionTimeMs": 45
  },
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4521,
        "left": 5479
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 3,
        "left": 57,
        "nextReset": "2025-01-15T09:31:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 3,
        "left": 57,
        "nextReset": "2025-01-15T09:31:00.000Z"
      }
    }
  }
}
```