Report usage

Record one tool call for a user of your product, and optionally deduct credits from their wallet.

POSThttps://api.ploba.app/api/v1/external/developer/report-usage

Authorization

Authorizationheaderrequired
Bearer and a secret key.

Body

appUserKeystringrequired
Identifies one user of your product. It must belong to your organisation.
toolNamestringrequired
The tool or operation that ran.
idempotencyKeystringrequired
Unique per call, up to 128 characters. Reuse it only to retry the same call.
inputTokensnumber
Defaults to 0.
outputTokensnumber
Defaults to 0.
creditsToDeductnumber
Credits to take from the user's wallet. Leave out to only record the call.
metadataobject
Anything else you want stored with the record.

Response

200 data is the stored usage record.

Errors

StatusWhen
401The secret key is missing, revoked or expired.
402The wallet doesn't have enough credits.
403The wallet is frozen.
404Unknown app user key for your organisation, or no wallet when deducting credits.
409That idempotency key was already used: the call is already recorded.
curl -X POST https://api.ploba.app/api/v1/external/developer/report-usage \
  -H "Authorization: Bearer $PLOBA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appUserKey": "<the user's app key>",
    "toolName": "search_docs",
    "inputTokens": 1200,
    "outputTokens": 340,
    "creditsToDeduct": 2,
    "idempotencyKey": "call_8f3a91"
  }'

Last updated Oct 9, 2026Report a problem with this page