Usage stats

Read how many credits an organization has consumed and inspect the underlying API activity. These endpoints use a Bearer JWT and require the BILLING_ACCESS permission on the organization.

Dates are ISO 8601 (YYYY-MM-DD or full timestamps). All endpoints are addressed by organizationId; resolve it from Organization.

Credit costs

Data-bearing calls consume credits from the organization's monthly allowance:

Call	Credit cost
Full dataset download (/files/:format)	10
Coordinates (/coordinates)	15
OGC items (/ogc/collections/:table/items)	10
OGC single feature (/items/:featureId)	1
SQL query (/sql/query)	25
Archive month	tier-scaled: basic 20 / team 10 / enterprise 0
Listing, metadata, and free samples	0

For the full credit and rate-limit model see Rate limits & credits.

Credit balance

GET /v1/credits/:organizationId

Returns the organization's current credit balance and allowance.

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/credits/org_8f3a2c7e"

Credit usage

GET /v1/credits/:organizationId/usage

Returns credit consumption for the organization. For a call-and-credit breakdown over a date range, use the API-usage totals below.

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/credits/org_8f3a2c7e/usage"

Usage totals

GET /v1/credits/:organizationId/api-usage?startDate=&endDate=

Returns aggregate calls and credits consumed over the date range.

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/credits/org_8f3a2c7e/api-usage?startDate=2026-05-01&endDate=2026-05-31"

{
  "organizationId": "org_8f3a2c7e",
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "totalCalls": 482,
  "creditsConsumed": 3120,
  "creditsRemaining": 6880
}

Field	Description
totalCalls	Number of API calls in the range.
creditsConsumed	Credits spent in the range.
creditsRemaining	Credits left in the current allowance.

Usage by key

GET /v1/credits/:organizationId/api-usage/by-key

Breaks the same totals down per API key, so you can attribute spend to a workload.

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/credits/org_8f3a2c7e/api-usage/by-key"

{
  "organizationId": "org_8f3a2c7e",
  "keys": [
    {
      "apiKeyId": "key_9a2c7e8b",
      "name": "etl-nightly",
      "totalCalls": 410,
      "creditsConsumed": 2900
    },
    {
      "apiKeyId": "key_1d4056a1",
      "name": "ad-hoc-analysis",
      "totalCalls": 72,
      "creditsConsumed": 220
    }
  ]
}

Call log

GET /v1/credits/:organizationId/api-logs?page=&limit=&startDate=&endDate=&apiKeyId=

Returns individual API calls, newest first. Use the filters to narrow by date range or key.

Parameter	Type	Description
page	integer	1-based page number. Default 1.
limit	integer	Items per page. Maximum 100.
startDate	string	ISO 8601 start of range.
endDate	string	ISO 8601 end of range.
apiKeyId	string	Filter to one key.

curl -H "Authorization: Bearer eyJhbGci..." \
  "https://api.topolab.nl/v1/credits/org_8f3a2c7e/api-logs?page=1&limit=50&startDate=2026-05-01&endDate=2026-05-31&apiKeyId=key_9a2c7e8b"

{
  "data": [
    {
      "timestamp": "2026-05-28T02:14:11Z",
      "apiKeyId": "key_9a2c7e8b",
      "endpoint": "/v1/dataset/transport_infrastructure_bushaltes/files/geojson",
      "status": 200,
      "credits": 10
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 410
}

Page through by incrementing page until page * limit >= total.

Per-key usage

For a single key without the organization scope, use the key-level endpoint documented in API keys:

GET /v1/api-keys/:id/usage?startDate=&endDate=

Errors

Status	Meaning
401	Missing or invalid Bearer token.
403	You lack BILLING_ACCESS on the organization.
404	The organization does not exist.
429	Rate limited, see Rate limits & credits.

Next

• Invoices, billing documents for the organization.
• API keys, attribute usage to individual keys.
• Need a higher allowance? Contact us.