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

# Retrieve API Credit Balance and Usage via GET Request

> Check your remaining API credits and monitor contact view and direct dial usage across your Clodura account with a single authenticated GET request.

The Credits endpoint gives you a real-time snapshot of your Clodura API credit balance and consumption. Use it to proactively monitor your account, prevent unexpected service interruptions, and understand how credits are being consumed across your integration. This is a simple `GET` request with no request body — just authenticate with your API key.

The response schema differs depending on your Clodura subscription plan. Prospect and Prospect Pro plans track contacts viewed and direct dials separately against fixed plan limits. Free Forever, Max, and PAYG plans use a single unified credit pool displayed as `remainingCredits`.

<Note>
  Every request to the Search People, Reveal Email, and Reveal Phone endpoints consumes credits from your account. See the individual endpoint pages for per-operation credit costs.
</Note>

## Endpoint

`GET /api/v1/credits`

## Request

### Headers

| Header      | Value                |
| ----------- | -------------------- |
| `X-API-KEY` | Your Clodura API key |

This endpoint accepts no request body.

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.clodura.ai/api/v1/credits \
    --header 'X-API-KEY: YOUR_API_KEY'
  ```

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

  url = "https://api.clodura.ai/api/v1/credits"

  headers = {
      "X-API-KEY": "YOUR_API_KEY"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```
</CodeGroup>

## Response

The response schema depends on your Clodura plan.

<Tabs>
  <Tab title="Prospect & Prospect Pro Plans">
    These plans track contact views and direct dials separately, each with their own maximum allowance based on your subscription tier.

    | Plan         | Total Contact Views | Total Direct Dials |
    | ------------ | ------------------- | ------------------ |
    | Prospect     | 1,000               | Plan limit         |
    | Prospect Pro | 2,000               | Plan limit         |

    <ResponseField name="contactsView" type="integer">
      Number of credits consumed so far to view contact email addresses using the Reveal Email endpoint.
    </ResponseField>

    <ResponseField name="maxContacts" type="string">
      Total contact view credits available on your current plan (e.g., `"1000"` for Prospect, `"2000"` for Prospect Pro).
    </ResponseField>

    <ResponseField name="directDials" type="integer">
      Number of credits consumed to retrieve contact phone numbers via integrated providers.
    </ResponseField>

    <ResponseField name="maxDirectDials" type="integer">
      Total direct dial credits available on your current plan.
    </ResponseField>

    ```json theme={null}
    {
      "contactsView": 142,
      "maxContacts": "1000",
      "directDials": 38,
      "maxDirectDials": 200
    }
    ```
  </Tab>

  <Tab title="Free Forever, Max & PAYG Plans">
    These plans use a unified credit pool called **Common Credits**. Common Credits are virtual points consumed whenever you unlock features or access contact details such as emails and phone numbers. Different actions consume different amounts of credits — refer to each endpoint's credit table for specifics.

    <ResponseField name="remainingCredits" type="number">
      Total credits remaining in your account across all features. When this reaches zero, API calls that consume credits will return a `402` error until you add more.
    </ResponseField>

    ```json theme={null}
    {
      "remainingCredits": 357
    }
    ```
  </Tab>
</Tabs>

## Plan Credit Summary

| Plan         | Credit Model                             | Starting Credits    |
| ------------ | ---------------------------------------- | ------------------- |
| Free Forever | Common Credits (`remainingCredits`)      | Plan allocation     |
| Max          | Common Credits (`remainingCredits`)      | Plan allocation     |
| PAYG         | Common Credits (`remainingCredits`)      | Purchase as needed  |
| Prospect     | Separate: `contactsView` / `directDials` | 1,000 contact views |
| Prospect Pro | Separate: `contactsView` / `directDials` | 2,000 contact views |

## Error Codes

| Status | Meaning                                                        |
| ------ | -------------------------------------------------------------- |
| `400`  | Bad request — malformed request                                |
| `401`  | Unauthorized — your API key is missing or invalid              |
| `403`  | Forbidden — you do not have permission to access this resource |
| `422`  | Unprocessable entity — validation error in the request         |
| `429`  | Rate limit exceeded — reduce request frequency                 |

<Info>
  The Credits endpoint is available to all plan types. If you receive a `403`, verify your API key is active and has not been revoked in the Clodura Developer Dashboard.
</Info>