Engramma

Usage

beginner

Monitor API usage, pattern consumption, latency metrics, and organization-level usage breakdowns.

Usage summary

GET/v1/usage/summary

Get a summary of your current period's usage against plan limits.

200Response
{
  "period": {
    "start": "2026-01-15T00:00:00Z",
    "end": "2026-02-15T00:00:00Z"
  },
  "patterns": {
    "used": 4523,
    "limit": 100000,
    "percentage": 4.5
  },
  "api_calls": {
    "total": 12847,
    "stores": 1523,
    "retrieves": 8234,
    "recalls": 1890,
    "explains": 450,
    "consolidations": 12,
    "other": 738
  },
  "storage_mb": 45.2,
  "rate_limit": {
    "current": 200,
    "peak_usage": 142
  }
}
import os
from engramma_cloud import EngrammaClient

client = EngrammaClient(api_key=os.environ["ENGRAMMA_API_KEY"])

usage = client.usage.summary()
print(f"Patterns: {usage.patterns.used}/{usage.patterns.limit} ({usage.patterns.percentage}%)")
print(f"API calls this period: {usage.api_calls.total}")
print(f"Storage: {usage.storage_mb} MB")

Usage history

GET/v1/usage/history

Get historical usage data for charting and trend analysis.

periodstringDefault: 30d

Time period: 7d, 30d, 90d, or 365d.

granularitystringDefault: daily

Data granularity: hourly, daily, or weekly.

200Response
{
  "period": "30d",
  "granularity": "daily",
  "data_points": [
    {
      "date": "2026-01-15",
      "api_calls": 423,
      "stores": 52,
      "retrieves": 301,
      "patterns_total": 4200,
      "storage_mb": 42.1
    },
    {
      "date": "2026-01-16",
      "api_calls": 512,
      "stores": 89,
      "retrieves": 345,
      "patterns_total": 4289,
      "storage_mb": 43
    }
  ]
}
history = client.usage.history(period="30d", granularity="daily")
for point in history.data_points:
    print(f"{point.date}: {point.api_calls} calls, {point.patterns_total} patterns")

Latency metrics

GET/v1/usage/latency

Get latency percentiles for your API calls over a recent period.

periodstringDefault: 24h

Time period: 1h, 6h, 24h, or 7d.

operationstring

Filter by operation type: store, retrieve, recall, explain, consolidate.

200Response
{
  "period": "24h",
  "operation": "all",
  "percentiles": {
    "p50": 12,
    "p75": 24,
    "p90": 48,
    "p95": 89,
    "p99": 210
  },
  "by_operation": {
    "store": {
      "p50": 15,
      "p95": 45
    },
    "retrieve": {
      "p50": 8,
      "p95": 32
    },
    "recall": {
      "p50": 28,
      "p95": 120
    },
    "explain": {
      "p50": 35,
      "p95": 150
    },
    "consolidate": {
      "p50": 2400,
      "p95": 8900
    }
  },
  "total_requests": 12847
}
latency = client.usage.latency(period="24h")
print(f"P50: {latency.percentiles.p50}ms")
print(f"P95: {latency.percentiles.p95}ms")
print(f"P99: {latency.percentiles.p99}ms")
for op, stats in latency.by_operation.items():
    print(f"  {op}: p50={stats.p50}ms, p95={stats.p95}ms")

Organization usage

GET/v1/usage/organization/{org_id}

Get usage breakdown for an organization, including per-key and per-member usage.

org_idstringrequired

Organization ID (path parameter).

200Response
{
  "org_id": "org_abc123",
  "period": {
    "start": "2026-01-15T00:00:00Z",
    "end": "2026-02-15T00:00:00Z"
  },
  "totals": {
    "api_calls": 12847,
    "patterns": 4523,
    "storage_mb": 45.2
  },
  "by_key": [
    {
      "key_id": "key_prod01",
      "name": "Production Backend",
      "api_calls": 10234,
      "percentage": 79.6
    },
    {
      "key_id": "key_dev01",
      "name": "Dev Environment",
      "api_calls": 2613,
      "percentage": 20.4
    }
  ]
}
org_usage = client.usage.organization(org_id="org_abc123")
print(f"Total calls: {org_usage.totals.api_calls}")
for key in org_usage.by_key:
    print(f"  {key.name}: {key.api_calls} ({key.percentage}%)")

Next steps

BillingGDPR