Skip to main content
GET
/
v1
/
usage
Get usage
curl --request GET \
  --url https://api.production.xtrace.ai/v1/usage \
  --header 'X-Org-Id: <api-key>' \
  --header 'x-api-key: <api-key>'
{
  "as_of": "<string>",
  "period": {
    "key": "<string>",
    "start": "<string>",
    "end": "<string>",
    "type": "calendar_month"
  },
  "storage": {
    "as_of": "<string>",
    "memories_active": 0,
    "episodes_active": 0,
    "artifacts_active": 0
  },
  "quota": {
    "rate_limit_req_per_min": 123,
    "monthly": {
      "period_key": "<string>",
      "resets_at": "<string>",
      "messages_ingested": {
        "used": 0,
        "limit": 123
      },
      "recalls": {
        "used": 0,
        "limit": 123
      }
    }
  },
  "object": "usage",
  "tier": "<string>",
  "operations": {
    "messages_ingested": 0,
    "recalls": 0,
    "requests": 0
  },
  "daily": [
    {
      "date": "<string>",
      "messages_ingested": 0,
      "recalls": 0,
      "requests": 0
    }
  ],
  "by_api_key": [
    {
      "api_key_hash": "<string>",
      "first_n": "<string>",
      "name": "<string>",
      "messages_ingested": 0,
      "recalls": 0,
      "requests": 0,
      "last_used_at": "<string>"
    }
  ]
}

Authorizations

x-api-key
string
header
required

Long-lived org API key. Alternative: Authorization: Bearer <key>.

X-Org-Id
string
header
required

Required alongside the API key (no key→org reverse index).

Headers

X-Portal-Usage-Key
string | null

Query Parameters

daily
boolean
default:false

Include the per-day daily[] array (one entry per calendar day in the period). Off by default to keep the response cheap; the dashboard chart opts in.

by_api_key
boolean
default:false

Include the per-API-key breakdown joined to APIKEY#{hash} for name / first_n. Off by default — extra DDB scans.

Response

Successful Response

Top-level shape for GET /v1/usage.

as_of
string
required

When this snapshot was computed.

period
Period · object
required
storage
StorageSnapshot · object
required

Currently-active per-type row counts from Qdrant.

Cached harder than operations (count(filter) is expensive); as_of reflects the mint time of the cached snapshot and may lag the response-level as_of.

quota
Quota · object
required
object
string
default:usage
Allowed value: "usage"
tier
string | null

Canonical tier value from ORG#SUB; None if unset.

operations
Operations · object

Period-total memory operation counters for the org.

daily
DailyEntry · object[] | null

None when ?daily=false (default); populated when ?daily=true.

by_api_key
ByApiKeyEntry · object[] | null

None when ?by_api_key=false (default); populated when ?by_api_key=true.