API reference
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
AuthorizationheaderrequiredBearerand 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
| Status | When |
|---|---|
| 401 | The secret key is missing, revoked or expired. |
| 402 | The wallet doesn't have enough credits. |
| 403 | The wallet is frozen. |
| 404 | Unknown app user key for your organisation, or no wallet when deducting credits. |
| 409 | That 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"
}'