Credit balance

The Credit Balance API returns your organization’s current credit balance as a single, read-only GET. Use it to check how many credits you have left before submitting uploads or contacts — for example, to top up ahead of a large batch, or to surface remaining credits in your own dashboard. It’s available to every account with an API key — no special access or scope needed, and it never costs a credit.

The balance object

Field	Type	Notes
`total`	integer	Total credits available — `subscription + purchased`. This is the number that gates credit-consuming endpoints.
`subscription`	integer	Credits from your monthly subscription allocation. Replenished each billing period and capped.
`purchased`	integer	Credits from one-time top-up purchases. Uncapped and never expire while your account is active.

Credits are consumed from the subscription pool first, then purchased.

Retrieve credit balance

GET /api/v1/credits/balance

Returns your organization’s current balance. The organization is resolved from your API key, so there are no parameters.

cURL
Node.js
Python

curl "https://api.optimaldial.com/api/v1/credits/balance" \
  -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"

const res = await fetch("https://api.optimaldial.com/api/v1/credits/balance", {
  headers: {
    Authorization: `Bearer ${process.env.OPTIMALDIAL_API_KEY}`,
  },
});
const balance = await res.json();

resp = requests.get(
    "https://api.optimaldial.com/api/v1/credits/balance",
    headers={"Authorization": f"Bearer {os.environ['OPTIMALDIAL_API_KEY']}"},
)
balance = resp.json()

Response

200 OK:

{
  "total": 1500,
  "subscription": 1000,
  "purchased": 500
}

Errors

Status	When
`401`	Missing, invalid, or revoked API key
`429`	Rate limit hit

Get started

Endpoint guides

Webhooks

API Reference

Resources

The balance object

Retrieve credit balance

Response

Errors

​The balance object

​Retrieve credit balance

​Response

​Errors

The balance object

Retrieve credit balance

Response

Errors