Retrieve API Credit Balance and Usage via 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.

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.

Endpoint

GET /api/v1/credits

Request

Headers

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

This endpoint accepts no request body.

Example Request

curl --request GET \
  --url https://api.clodura.ai/api/v1/credits \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

The response schema depends on your Clodura plan.

Prospect & Prospect Pro Plans
Free Forever, Max & PAYG 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

contactsView

integer

Number of credits consumed so far to view contact email addresses using the Reveal Email endpoint.

maxContacts

string

Total contact view credits available on your current plan (e.g., "1000" for Prospect, "2000" for Prospect Pro).

directDials

integer

Number of credits consumed to retrieve contact phone numbers via integrated providers.

maxDirectDials

integer

Total direct dial credits available on your current plan.

{
  "contactsView": 142,
  "maxContacts": "1000",
  "directDials": 38,
  "maxDirectDials": 200
}

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.

remainingCredits

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.

{
  "remainingCredits": 357
}

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

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.

​Endpoint

​Request

​Headers

​Example Request

​Response

​Plan Credit Summary

​Error Codes

Endpoint

Request

Headers

Example Request

Response

Plan Credit Summary

Error Codes