External Service Limits

The platform enforces call-rate limits and tracks usage costs for every external API integration. Limits are configured per service in application.yml; usage data is available via a tenant-scoped admin endpoint.

Rate limit configuration

Add a mosterd.rate-limits.services block to application.yml. Each key is a service name (see Service names below).

mosterd:
  rate-limits:
    services:
      gemini:
        calls: 100
        window: HOURS
        units: 500000
      document-ai:
        calls: 50
        window: HOURS
      kvk:
        calls: 500
        window: DAYS
      companies-house:
        calls: 600
        window: DAYS
      webservices:
        calls: 1000
        window: DAYS

Field	Type	Required	Description
calls	integer	yes	Maximum number of calls per window
window	HOURS | DAYS	yes	Reset interval for the call counter
units	integer	no	Cumulative units limit per window (tokens for gemini, pages for document-ai)
budgetEur	decimal	no	Monthly spend budget in EUR — informational, shown in the usage response

When the calls limit is reached the platform returns HTTP 429 to the script or import that triggered the call. The counter resets automatically when the current hour or day rolls over. The units limit works independently: it accumulates across the window and blocks further calls once reached.

Service names

Service name	Gateway(s)	Tracked cost
gemini	Ai, DocumentTriage, Invoice	Tokens (input + output) at per-model USD rate
document-ai	MarkdownConversion	Pages processed ($0.01 / page)
kvk	CompanyRegister (NL), CompanySearch (NL)	€0.02 per Basisprofiel lookup; searches are free
companies-house	CompanyRegister (GB), CompanySearch (GB)	Free — rate limit only
webservices	Webservices	€0.0707 per address enrichment call

See Gateways Reference for gateway parameters and usage.

Exchange rate configuration

Costs tracked in non-EUR currencies are converted using configurable exchange rates. Add rates under mosterd.exchange-rates:

mosterd:
  exchange-rates:
    USD: 1.1641   # EUR per USD (amount / rate)

If no rate is configured for a currency, costLocal is null on records for that service.

Usage data

Every external call is recorded as a system.serviceCallLog DataObject. These records are queryable and aggregatable using the same endpoints as regular data types.

Fields

Field	Type	Description
service	LIST (system.externalService)	Service identifier
timestamp	DATETIME	When the call was made
success	BOOLEAN	Whether the call completed without error
costUnits	INTEGER	Units consumed (tokens for gemini, pages for document-ai); null if not applicable
costUnit	TEXT	Unit label for costUnits (e.g. tokens, pages)
cost	CURRENCY	Cost in the service's native currency
costLocal	CURRENCY	Cost normalized to EUR; null if no exchange rate is configured
reference	TEXT	Identifier of the object that triggered the call

Endpoints

All endpoints require admin authorization. Replace {tenantId} with the tenant UUID.

GET /system/{tenantId}/serviceCallLogs

Returns a paginated list of log records. Supports the same filter and sort parameters as standard data queries. See API Search for filter syntax.

GET /system/{tenantId}/serviceCallLogs/{id}

Returns a single log record by ID.

GET /system/{tenantId}/serviceCallLogs/aggregations

Returns aggregated values for the matching records. The default view includes SUM aggregates for costUnits and costLocal. See API Aggregations for the response format.