Every non-preview People API call that returns person records counts those records against your org's monthly record quota. You can see your consumption in two places: the response headers on every People API call, and a dedicated usage endpoint on the Billing API that returns the full picture for the current period.

What counts as a credit

A credit is consumed for each unique person record returned by a non-preview People API endpoint:

• /find
• /search
• /person/<id>
• /persons/lookup_by_ids

The preview endpoints (/find/preview, /search/preview) never consume credits — they are free to call and return the X-LDT-Credits-Cost header so you can see what the equivalent non-preview call would cost before committing to it.

Credits are tracked per person id, per billing period. Once your org has been charged for a specific person id in the current period, any subsequent call that returns that same person id — from any endpoint, any API key, any user on the org — is free. You are never charged twice for the same person within the same billing period.

Response headers

Every successful People API response from the endpoints above includes:

When a request exceeds the remaining quota, the People API returns 402 Payment Required with the same headers so clients can surface the cap to users.

Fetching the full usage picture

The response headers only reflect the call you just made. To see your total consumption for the current period — or to see usage for unlimited-access orgs, where X-LDT-Credits-Remaining is not returned — call the Billing API usage endpoint:

GET https://gotlivedata.io/api/billing/v1/<org_id>/usage

Authenticate with a Bearer token the same way you do for the People API (see Auth). The caller must have at least the viewer role on the org.

Query parameters

Response

{
  "usage": [
    {
      "date_from": "2026-04-14T00:00:00+00:00",
      "date_to": "2026-05-13T23:59:59+00:00",
      "org_id": "o_abc123",
      "product_name": "people",
      "usage_type": "api",
      "total_usage": 1843,
      "quota": 10000,
      "subscription_id": "sub_1Nxyz...",
      "subscription_ends_at": "2026-05-14T00:00:00+00:00"
    }
  ]
}

curl --request GET \
  --url 'https://gotlivedata.io/api/billing/v1/o_abc123/usage' \
  --header 'Authorization: Bearer <accessToken>'

This endpoint is the recommended way to surface current-period usage in UIs and internal dashboards, and it is the only way to see consumption for unlimited-access orgs since they do not receive X-LDT-Credits-Remaining on People API responses.

How the monthly period is calculated

The "current period" that X-LDT-Credits-Remaining and the /usage endpoint refer to depends on how your org is set up:

• Free tier and unlimited-access orgs use calendar months — the period runs from the first of the month through the last second of the month, in UTC.
• Metered plans use subscription-anchored months — the period starts on the same day of the month as the day you created your subscription. For example, a subscription created on the 14th rolls over on the 14th of each following month.

Usage counters and the list of already-credited person ids both reset at the start of each new period.

Unlimited access

If your org has unlimited People API access:

• X-LDT-Credits-Used is still returned on every call so you can see call volume.
• X-LDT-Credits-Remaining is omitted entirely — no cap is enforced and calls will not be rejected for exceeding a limit.
• The /usage endpoint returns quota: null. total_usage is still populated so you can track volume for the period.

Clients should treat a missing X-LDT-Credits-Remaining header or a null quota as "no limit" rather than a zero or negative value.