Credits

Use the credits endpoints to inspect your organisation's meter balances and recent consumption. The OAuth client resolves organisation context; you do not pass an organisation id in the path.

OAuth scope

• credits.read: read balances and history.
• Request this scope when exchanging client credentials.
• Missing credits.read returns HTTP 403 with a public authorization error (for example insufficient_scope). Public error bodies do not name internal permission keys.

Credit balances

curl "https://api.musimap.com/v1/me/credits" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

The response lists balances by meter with available and reserved amounts. Reads do not consume credits. Organisation context comes from the access token.

{
  "status": 200,
  "message": "OK",
  "data": {
    "balances": [
      { "meter": "tagging", "available": 1200, "reserved": 0 },
      { "meter": "profiling", "available": 80, "reserved": 0 }
    ]
  }
}

Credit history

curl "https://api.musimap.com/v1/me/credits/history?page=1&page_size=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

History is paginated. Optional meter filters to one meter. Each entry includes id, meter, amount, created_at, and a short description.

How credits relate to product calls

• Live tagging (POST /v1/tagging) consumes tagging credits.
• Live tagging with persist: true consumes two credits when both live tagging and persisted analysis run (one each).
• Creating a MusiProfile with POST /v1/profiling/profiles consumes profiling credits.
• Inventory, search, taxonomy, and credits reads do not consume credits.

See Tagging and Profiling for request shapes.