Credits

Use the credits endpoints to inspect your organisation's credit balances and recent consumption for Tagging, Profiling, Fingerprinting, and Discovery. 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

Request

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

The response lists balances under meters. Each row uses a public capability key in meter_key (tagging, profiling, fingerprinting, discovery) and remaining capacity fields such as credits_remaining and remaining_total. Reads do not consume credits. Organisation context comes from the access token.

Response

{
  "status": 200,
  "message": "OK",
  "data": {
    "organization_id": "0190…",
    "meters": [
      { "meter_key": "tagging", "credits_remaining": 1200, "remaining_total": 1200 },
      { "meter_key": "profiling", "credits_remaining": 80, "remaining_total": 80 },
      { "meter_key": "fingerprinting", "credits_remaining": 0, "remaining_total": 0 },
      { "meter_key": "discovery", "credits_remaining": 40, "remaining_total": 40 }
    ]
  }
}

Credit history

Request

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

History is paginated. Optional meter filters to one public capability key (tagging, profiling, fingerprinting, or discovery). Each entry includes id, meter_key, amount and timing fields for the ledger movement.

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.
• Discovery (POST /v1/discovery) consumes Discovery credits: the first successful billable Discovery turn costs 1 Discovery credit and covers up to 10 billable turns in that session; each additional billable turn after the tenth costs 1 additional Discovery credit. Empty sessions are free. See Discovery.
• Inventory, catalogue search, taxonomy, and credits reads do not consume credits.

See Tagging, Profiling, and Discovery for request shapes.