Usage

Get credit balance

Returns the authenticated user's spendable credit balance. total is the single number to show (community + purchased); effective spendable is total - reserved. The community / purchased split is retained for back-compat and refund-to-origin accounting: community credits (signup grant for new users; legacy monthly refill for accounts created before the pricing v1 cutoff), purchased credits (carry forward across months), and reserved credits currently held by in-flight analyze calls.

Dual auth

Supports both Bearer API key (external callers) and x-internal-secret header plus ?userId=<id> query param (server-to-server, for dashboard integrations).

get/v1/usage

Request

  • Base URL: https://api.phototology.com
  • URL: https://api.phototology.com/v1/usage
  • Auth: one of:
    • HTTP bearer
    • API key in header x-internal-secret

Query parameters

userIdstring

User ID. Required only when using x-internal-secret auth.

Example:usr_01j9kqm7x8n2f4
tier'starter'

Legacy tier query param. Only starter is valid; the Growth subscription tier was retired in 2026-05-17. The field is accepted for backward compatibility with phototology-web server actions that may still pass it; the response tier is always starter.

Example:starter

Response

Current credit balance for the authenticated user.

tierstring required

API key tier. Historically starter or growth; the Growth subscription tier was retired in pricing v1 (2026-05-17) so this field now always returns starter. The field is kept in the response shape for SDK backward compatibility and may be removed in a future major version.

totalinteger required

Single spendable credit balance (community + purchased). This is the number to show and reason about; effective spendable credit is total - reserved. Added 2026-05-29 (additive, non-breaking). The community / purchased split below is retained for back-compat and refund-to-origin accounting, not as two balances the holder manages.

reservedinteger required

Credits currently held in reserve for in-flight analyze calls.

Example response

{
  "tier": "starter",
  "total": 5743,
  "community": {
    "balance": 743
  },
  "purchased": {
    "balance": 5000
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.