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

# Get Credit Usage

Get your current billing cycle credit usage at a glance -- plan info, credits used, credits remaining, and a breakdown by entity type.

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.v2.dealmachine.com/v1/usage \
    -H "Authorization: Bearer dm_sk_live_xxx"
  ```

  ```typescript Node.js theme={null}
  const response = await fetch('https://api.v2.dealmachine.com/v1/usage', {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  const usage = await response.json();
  console.log(`${usage.credits.remaining} credits remaining`);
  ```

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

  response = requests.get(
      'https://api.v2.dealmachine.com/v1/usage',
      headers={'Authorization': f'Bearer {api_key}'}
  )

  usage = response.json()
  print(f"{usage['credits']['remaining']} credits remaining")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "plan": {
      "name": "Pro",
      "is_paid": true
    },
    "billing_cycle": {
      "start": "2025-06-01T00:00:00.000Z",
      "end": "2025-07-01T00:00:00.000Z"
    },
    "credits": {
      "included": 20000,
      "total_cap": 21000,
      "total_available": 19477,
      "base_included": 20000,
      "monthly_credit_grant_cap": 0,
      "monthly_included": 20000,
      "additional_credit_balance": 1000,
      "used": 1523,
      "remaining": 19477,
      "monthly_remaining": 18477,
      "additional_remaining": 1000,
      "overage": 0,
      "pools": {
        "monthly": { "included": 20000, "used": 1523, "remaining": 18477 },
        "additional": { "available": 1000, "used": 0, "remaining": 1000 }
      },
      "breakdown": {
        "properties": 847,
        "people": 676,
        "companies": 0
      }
    }
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "invalid_api_key",
      "message": "Invalid API key",
      "request_id": "req_abc123"
    }
  }
  ```
</ResponseExample>

## Response Fields

### `plan`

| Field     | Type    | Description                                |
| --------- | ------- | ------------------------------------------ |
| `name`    | string  | Plan name (e.g. `No plan`, `Basic`, `Pro`) |
| `is_paid` | boolean | Whether this is a paid plan                |

### `billing_cycle`

| Field   | Type   | Description                                                            |
| ------- | ------ | ---------------------------------------------------------------------- |
| `start` | string | ISO 8601 start of the current billing cycle                            |
| `end`   | string | ISO 8601 end of the current billing cycle (credits reset at this time) |

### `credits`

| Field                       | Type   | Description                                                |
| --------------------------- | ------ | ---------------------------------------------------------- |
| `included`                  | number | Monthly credits included in the current cycle              |
| `total_cap`                 | number | Total current-cycle capacity, including additional credits |
| `total_available`           | number | Live spendable balance remaining across all pools          |
| `base_included`             | number | Plan credits before temporary grants                       |
| `monthly_credit_grant_cap`  | number | Temporary credits granted for this cycle                   |
| `monthly_included`          | number | Plan credits plus temporary monthly grants                 |
| `additional_credit_balance` | number | Current durable additional-credit wallet balance           |
| `used`                      | number | Credits consumed so far this billing cycle                 |
| `remaining`                 | number | Same live spendable balance as `total_available`           |
| `monthly_remaining`         | number | Monthly credits remaining                                  |
| `additional_remaining`      | number | Additional credits remaining after pending reservations    |
| `overage`                   | number | Historical usage recorded beyond total capacity            |

### `credits.breakdown`

| Field        | Type   | Description                                   |
| ------------ | ------ | --------------------------------------------- |
| `properties` | number | Unique properties accessed this billing cycle |
| `people`     | number | Unique people accessed this billing cycle     |
| `companies`  | number | Unique companies accessed this billing cycle  |

<Note>
  Credits are **deduplicated** within your billing period. Accessing the same property or contact
  multiple times in one billing cycle only counts once.
</Note>

<Note>
  `total_available` and `remaining` are live balances. They reconcile the shared Redis reservation
  counter with the durable credit ledger. `total_cap` is the allowance; do not treat it as the
  remaining balance.
</Note>

<Tip>
  Call this endpoint before large batch operations to check your remaining credits and avoid partial
  results or credit-limit errors.
</Tip>