MassRelay
GuidesAPI referenceRun it yourselfChangelogopenapi.json

Home / Docs / API reference

/v1/credits

GET /v1/credits

Authentication relay key (bearer)

Example request

curl
curl https://api.massrelay.ai/v1/credits \
  -H "Authorization: Bearer $RELAY_KEY"
Python
import os, requests

r = requests.get(
    "https://api.massrelay.ai/v1/credits",
    headers={"Authorization": f"Bearer {os.environ['RELAY_KEY']}"},
)
r.raise_for_status()
print(r.json())
TypeScript
const r = await fetch("https://api.massrelay.ai/v1/credits", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.RELAY_KEY}` },
});
if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);
console.log(await r.json());

Response

FieldTypeDescription
object requiredstringThe kind of object returned, for example chat.completion. Always "credits".
unit requiredstring Always "mu".
displayCurrency requiredstring or null
totalBalanceMu requiredintegermicro-dollars, the unit of account
totalAvailableMu requiredintegermicro-dollars, the unit of account
wallets requiredarray of object
wallets[].id requiredstringThe answer's id.
wallets[].kind requiredobject One of: prepaid, allowance, grant, pool, sponsor.
wallets[].balanceMu requiredintegermicro-dollars, the unit of account
wallets[].heldMu requiredintegermicro-dollars, the unit of account
wallets[].availableMu requiredintegermicro-dollars, the unit of account
wallets[].currency requiredstring or null
wallets[].expiresAt requiredstring or null
freeAllowanceLeft requiredinteger or nullrequests left in this month's free allowance; null when the plan has none
freeAllowance requiredobject or null
freeAllowance.meterstring
freeAllowance.planstring or null
freeAllowance.allowanceinteger
freeAllowance.usedinteger
freeAllowance.resetsAtstring
Example response (shape)
{
  "object": "credits",
  "unit": "mu",
  "displayCurrency": "<displayCurrency>",
  "totalBalanceMu": 0,
  "totalAvailableMu": 0,
  "wallets": [
    {
      "id": "<id>",
      "kind": "prepaid",
      "balanceMu": 0,
      "heldMu": 0,
      "availableMu": 0,
      "currency": "<currency>",
      "expiresAt": "<expiresAt>"
    }
  ],
  "freeAllowanceLeft": "<freeAllowanceLeft>",
  "freeAllowance": {
    "meter": "<meter>",
    "plan": "<plan>",
    "allowance": 0,
    "used": 0,
    "resetsAt": "<resetsAt>"
  }
}

Common errors

  • 401 invalid_api_key
  • 403 insufficient_scope
  • 429 over the request rate; read Retry-After

Every error has the same JSON shape; see Errors and Limits.

Full schema (JSON)

Response schema

{
  "description": "The wallets are the key's workspace's own (owner kind workspace).",
  "type": "object",
  "required": [
    "object",
    "unit",
    "displayCurrency",
    "totalBalanceMu",
    "totalAvailableMu",
    "wallets",
    "freeAllowanceLeft",
    "freeAllowance"
  ],
  "properties": {
    "object": {
      "const": "credits"
    },
    "unit": {
      "const": "mu"
    },
    "displayCurrency": {
      "type": [
        "string",
        "null"
      ]
    },
    "totalBalanceMu": {
      "type": "integer",
      "description": "micro-dollars, the unit of account"
    },
    "totalAvailableMu": {
      "type": "integer",
      "description": "micro-dollars, the unit of account"
    },
    "wallets": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "balanceMu",
          "heldMu",
          "availableMu",
          "currency",
          "expiresAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "prepaid",
              "allowance",
              "grant",
              "pool",
              "sponsor"
            ]
          },
          "balanceMu": {
            "type": "integer",
            "description": "micro-dollars, the unit of account"
          },
          "heldMu": {
            "type": "integer",
            "description": "micro-dollars, the unit of account"
          },
          "availableMu": {
            "type": "integer",
            "description": "micro-dollars, the unit of account"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    },
    "freeAllowanceLeft": {
      "type": [
        "integer",
        "null"
      ],
      "description": "requests left in this month's free allowance; null when the plan has none"
    },
    "freeAllowance": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "meter": {
          "type": "string"
        },
        "plan": {
          "type": [
            "string",
            "null"
          ]
        },
        "allowance": {
          "type": "integer"
        },
        "used": {
          "type": "integer"
        },
        "resetsAt": {
          "type": "string"
        }
      }
    }
  }
}