Credit Balance

Returns the current plan, the remaining and used credits, the billing status and the account identifiers. It is a read-only call: it does not use credits and works even with a zero balance.

⚠

Change on October 4, 2026

Starting today, GET /quota and the MCP tool get_quota_info no longer return staticCreditCost, realtimeCreditCost, overageEnabled, overagePriceInCents, staticRateLimitPerMinute and realtimeRateLimitPerMinute. The per-lookup costs (default of 1 credit for the Simple Lookup and 1.5 for the Real-Time Lookup) and the overage rules of your plan are in the dashboard. The default limits are 30/min for the Simple Lookup (each batch submission counts as 1) and 5/min for the Real-Time Lookup. Custom plans may have different limits, so confirm with CPFHub.io support. 429 responses include the Retry-After header. See Usage Limits.

Endpoint

GEThttps://api.cpfhub.io/quota

Authentication

Send your API key in the x-api-key header. See Authentication.

Parameters

This endpoint takes no path or query parameters.

Headers

Header	Required	Description
`x-api-key`	Yes	Your CPFHub.io API key

Request examples

curl "https://api.cpfhub.io/quota" \
  -H "x-api-key: $CPFHUB_API_KEY"

Success response

HTTP 200 OK

JSON

{
  "success": true,
  "data": {
    "plan": "Básico",
    "remainingCredits": 750,
    "usedCredits": 250,
    "billingStatus": "active",
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "email": "usuario@exemplo.com"
  }
}

Response fields

Field	Type	Description
`success`	`boolean`	`true` if the request was processed successfully
`data.plan`	`string`	Name of your subscription plan: `Grátis`, `Micro`, `Básico`, `Intermediário`, `Avançado` or a custom plan. These are the Portuguese names returned by the API, and the Pro plan on the website matches Micro, Básico, Intermediário or Avançado depending on volume (see Usage Limits). Accounts without a subscription return `"unknown"`
`data.remainingCredits`	`integer`	Credits still left in the period allowance, rounded down. A balance of 1.4 shows as `1`. It never goes negative: on plans with overage it stays at `0` while lookups keep being billed as overage
`data.usedCredits`	`number`	Credits used by the whole account (all keys) in the current period. On paid plans, the period is the subscription's billing cycle. On the Free plan, it is the current month (UTC). It can have decimals and go past the allowance on plans with overage
`data.billingStatus`	`"active"` \| `"free"`	Plan eligibility: `"active"` when the account has a subscription that gives access to the plan, including a subscription on the Free plan and statuses such as `past_due`. `"free"` when there is no valid subscription, for example `canceled`, `unpaid` or `incomplete_expired`. In that case, `plan` may come as `"unknown"`
`data.userId`	`string`	Unique user identifier
`data.email`	`string`	Email address associated with the account

✦

Works with a zero balance

GET /quota keeps responding when the credit balance reaches zero. That way you can check the balance from your system and act before lookups stop.

ℹ

Fractional balance

The Simple Lookup costs 1 credit and the Real-Time Lookup costs 1.5 credits by default, so the balance can end up fractional. Because remainingCredits is rounded down, check your plan's specific costs in the dashboard before deciding whether the balance covers the next lookup.

How to monitor the balance

Create an alert when remainingCredits drops below a threshold of your own (for example, 10% of the allowance).
Track usedCredits to measure total consumption in the period.
Check the dashboard for the costs and overage rules specific to your plan.
The default limits are 30/min for the Simple Lookup (each batch submission counts as 1) and 5/min for the Real-Time Lookup. Custom plans may have different limits, so confirm with CPFHub.io support. Above the limit, the API responds 429 with the Retry-After header.
The period allowance is usedCredits + remainingCredits while the balance has not reached zero.

Status codes

Status	Description
`200 OK`	Balance check succeeded
`401 Unauthorized`	Missing, invalid or inactive API key
`403 Forbidden`	Inactive or blocked account
`500 Internal Server Error`	Internal error while validating the subscription (`"Erro ao validar assinatura"`, error validating subscription)
`503 Service Unavailable`	Balance temporarily unavailable (`error: "usage_unavailable"`). Try again in a few seconds.

In these errors, error comes as a string. GET /quota has no per-minute limit and does not use credits.

⚠

Keep your API key safe

Never expose your API key in public code, repositories or applications that run directly in the browser. Always make API calls from your back end or server.

For the full list of error codes and messages, see Error Codes.

Updated on October 3, 2026