Usage Endpoint

Overview

There are two ways to monitor your API consumption:

Response headers — present on every API response, ideal for agents and in-flight self-regulation
GET /v1/usage endpoint — returns a full breakdown, suitable for dashboards, logging pipelines, or pre-flight checks before a batch job

When to use which:

Use the headers if you just need to know whether to keep going. Your client receives X-Giltiq-Usage on every validation response — no extra request needed.
Use this endpoint when you want to log usage at the start of a run, build a dashboard widget, or check remaining quota before triggering a large batch.

Response Headers

These headers are present on every API response (not just /v1/usage):

Header	Format	Description
`X-Giltiq-Usage`	`84/100`	Validations used vs. total limit for the current period
`X-Giltiq-Upgrade`	URL string	Present only when usage exceeds 80% of your plan limit; links to the upgrade page

Example headers:

X-Giltiq-Usage: 84/100
X-Giltiq-Upgrade: https://giltiq.de/pricing/

X-Giltiq-Upgrade is omitted when usage is below 80%. When it appears, the value is always https://giltiq.de/pricing/.

Cross-reference: see the Authentication guide for full header documentation.

`GET /v1/usage`

Returns your current plan and consumption for the billing period.

Authentication: Required (API key — Tier 1 and above)

Request

curl https://api.giltiq.de/v1/usage \
  -H "X-API-Key: gq_live_your_key_here"

Response Schema

Field	Type	Description
`plan`	string	Current plan: `free`, `starter`, `business`, or `enterprise`
`period.start`	ISO 8601	Start of the current billing period
`period.end`	ISO 8601	End of the current billing period
`requests.used`	integer	Validations consumed so far this period
`requests.remaining`	integer	Validations remaining (`limit − used`)
`requests.limit`	integer	Total validations included in your plan for this period

Example Response

{
  "plan": "free",
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-04-01T00:00:00Z"
  },
  "requests": {
    "used": 84,
    "remaining": 16,
    "limit": 100
  }
}

Quota Counting Rules

Not every API call consumes quota. The counting rules are:

Outcome	Counted?	Notes
Valid response (any source)	Yes	You received usable data
Cached/stale result returned	Yes	You received usable data
`SOURCE_UNAVAILABLE` with no cached fallback	No	All upstream sources were down; no usable data returned

In plain terms: you only pay for lookups that return usable data. If all upstream sources (VIES, BZSt, and fallbacks) are unavailable and no cached result can be served, the call is not counted against your quota.

Abuse cap: To prevent quota gaming, a maximum of 3 uncounted retries per unique VAT ID per hour are allowed. Retries beyond this cap are counted regardless of outcome.

Tier 0 Note

Anonymous callers (no API key) cannot access this endpoint. A 401 Unauthorized response is returned with a registration prompt:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key required. Register at https://giltiq.de to get started.",
    "request_id": "abc123"
  }
}

To use this endpoint, register for a free API key.