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,
    "daily_caps": {
      "reads_remaining": 123,
      "writes_remaining": 123,
      "resets_at": "<string>"
    },
    "monthly": {
      "consumed_units": 0,
      "included_units": 123,
      "overage_units": 0,
      "memories_cap": 123,
      "ops_cap": 123
    }
  },
  "object": "usage",
  "tier": "<string>",
  "operations": {
    "writes": {
      "requests": 0,
      "memories_created": 0,
      "units": 0
    },
    "reads": {
      "requests": 0,
      "memories_returned": 0,
      "units": 0
    },
    "total_units": 0,
    "total_requests": 0
  },
  "daily": [
    {
      "date": "<string>",
      "writes": {
        "requests": 0,
        "memories_created": 0,
        "units": 0
      },
      "reads": {
        "requests": 0,
        "memories_returned": 0,
        "units": 0
      }
    }
  ],
  "by_api_key": [
    {
      "api_key_hash": "<string>",
      "first_n": "<string>",
      "name": "<string>",
      "writes": {
        "requests": 0,
        "memories_created": 0,
        "units": 0
      },
      "reads": {
        "requests": 0,
        "memories_returned": 0,
        "units": 0
      },
      "last_used_at": "<string>"
    }
  ]
}

usage

Get usage

Aggregate the org’s MONTHLY UsageMetrics rows for the current calendar month, plus DAILY rows if requested, plus an inline Qdrant storage snapshot.

Computed values:

operations.{writes,reads}.units mirrors the DDB writeUsage / readUsage columns.
operations.{writes,reads}.memories_{created,returned} mirrors the per-row memories_count attribute (added in PR 4).
operations.{writes,reads}.requests mirrors the per-row requests attribute (added in PR 4).
operations.total_units is the running sanity-check against ORG#SUB.periodUsageUnits.

GET

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,
    "daily_caps": {
      "reads_remaining": 123,
      "writes_remaining": 123,
      "resets_at": "<string>"
    },
    "monthly": {
      "consumed_units": 0,
      "included_units": 123,
      "overage_units": 0,
      "memories_cap": 123,
      "ops_cap": 123
    }
  },
  "object": "usage",
  "tier": "<string>",
  "operations": {
    "writes": {
      "requests": 0,
      "memories_created": 0,
      "units": 0
    },
    "reads": {
      "requests": 0,
      "memories_returned": 0,
      "units": 0
    },
    "total_units": 0,
    "total_requests": 0
  },
  "daily": [
    {
      "date": "<string>",
      "writes": {
        "requests": 0,
        "memories_created": 0,
        "units": 0
      },
      "reads": {
        "requests": 0,
        "memories_returned": 0,
        "units": 0
      }
    }
  ],
  "by_api_key": [
    {
      "api_key_hash": "<string>",
      "first_n": "<string>",
      "name": "<string>",
      "writes": {
        "requests": 0,
        "memories_created": 0,
        "units": 0
      },
      "reads": {
        "requests": 0,
        "memories_returned": 0,
        "units": 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-Service-Token

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

Show child attributes

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.

Show child attributes

quota

Quota · object

required

Show child attributes

object

string

default:usage

Allowed value: "usage"

tier

string | null

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

operations

Operations · object

Period-totals operations envelope.

Show child attributes

daily

DailyEntry · object[] | null

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

Show child attributes

by_api_key

ByApiKeyEntry · object[] | null

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

Show child attributes

Update memory

⌘I

Documentation Index

Authorizations

Headers

Query Parameters

Response