Usage
Report usage
Record each tool call your users make. Send tokens for your own records, and credits to charge the user's prepaid balance.
Send a usage record
After a tool call finishes, send one record to POST /report-usage:
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"
}'Idempotency and retries
Every record needs an idempotencyKey, unique to that call (up to 128 characters). Each key is accepted once, so if a request times out you can retry with the same key and the call is never recorded or charged twice. If the first attempt had already gone through, the retry returns 409: treat that as recorded. Use a new key for every new call.
Credits
- Without
creditsToDeduct, the call is only recorded. - With it, that many credits come off the user’s wallet in the same step.
- If the balance is too low the call fails with 402, and nothing is recorded. A frozen wallet returns 403.