MassRelay
GuidesAPI referenceRun it yourselfChangelogopenapi.json

Home / Docs / API reference

/v1/usage

GET /v1/usage

Authentication relay key (bearer)

Example request

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

r = requests.get(
    "https://api.massrelay.ai/v1/usage",
    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/usage", {
  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 "usage".
unit requiredstring Always "mu".
period requiredobject
period.from requiredstring
period.to requiredstring
endUserstring
requests requiredinteger
inputTokens requiredinteger
outputTokens requiredinteger
costMu requiredintegermicro-dollars, the unit of account
byEndUserarray of object
byEndUser[].endUser requiredstring
byEndUser[].requests requiredinteger
byEndUser[].inputTokens requiredinteger
byEndUser[].outputTokens requiredinteger
byEndUser[].costMu requiredintegermicro-dollars, the unit of account
Example response (shape)
{
  "object": "usage",
  "unit": "mu",
  "period": {
    "from": "<from>",
    "to": "<to>"
  },
  "endUser": "<endUser>",
  "requests": 0,
  "inputTokens": 0,
  "outputTokens": 0,
  "costMu": 0,
  "byEndUser": [
    {
      "endUser": "<endUser>",
      "requests": 0,
      "inputTokens": 0,
      "outputTokens": 0,
      "costMu": 0
    }
  ]
}

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": "Query: from, to (ISO date or datetime, default the UTC calendar month), end_user (one tag), group_by=end_user (one row per tag).",
  "type": "object",
  "required": [
    "object",
    "unit",
    "period",
    "requests",
    "inputTokens",
    "outputTokens",
    "costMu"
  ],
  "properties": {
    "object": {
      "const": "usage"
    },
    "unit": {
      "const": "mu"
    },
    "period": {
      "type": "object",
      "required": [
        "from",
        "to"
      ],
      "properties": {
        "from": {
          "type": "string"
        },
        "to": {
          "type": "string"
        }
      }
    },
    "endUser": {
      "type": "string"
    },
    "requests": {
      "type": "integer"
    },
    "inputTokens": {
      "type": "integer"
    },
    "outputTokens": {
      "type": "integer"
    },
    "costMu": {
      "type": "integer",
      "description": "micro-dollars, the unit of account"
    },
    "byEndUser": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "endUser",
          "requests",
          "inputTokens",
          "outputTokens",
          "costMu"
        ],
        "properties": {
          "endUser": {
            "type": "string"
          },
          "requests": {
            "type": "integer"
          },
          "inputTokens": {
            "type": "integer"
          },
          "outputTokens": {
            "type": "integer"
          },
          "costMu": {
            "type": "integer",
            "description": "micro-dollars, the unit of account"
          }
        }
      }
    }
  }
}