Usage Metrics API

The usage metrics endpoint provides usage statistics and quota information for the authenticated tenant.

GET /v1/usage-metrics

Request

curl "https://api.hippocortex.dev/v1/usage-metrics?period=24h&granularity=hour" \
  -H "Authorization: Bearer hx_live_..."

Query Parameters

Parameter	Type	Default	Options	Description
`period`	string	`24h`	`1h`, `24h`, `7d`, `30d`	Time window
`granularity`	string	`hour`	`minute`, `hour`, `day`	Data point resolution

Response

{
  "ok": true,
  "data": {
    "period": {
      "start": "2025-01-14T10:00:00Z",
      "end": "2025-01-15T10:00:00Z",
      "granularity": "hour"
    },
    "usage": {
      "events": {
        "total": 1250,
        "ingested": 1200,
        "duplicates": 45,
        "errors": 5,
        "byType": {
          "message": 450,
          "tool_call": 320,
          "tool_result": 280,
          "outcome": 95,
          "error": 55
        }
      },
      "compilations": {
        "total": 3,
        "artifactsCreated": 12,
        "artifactsUpdated": 8
      },
      "syntheses": {
        "total": 89,
        "avgTokensUsed": 3200,
        "avgCompressionRatio": 2.8
      }
    },
    "quota": {
      "plan": "developer",
      "eventsLimit": 50000,
      "eventsUsed": 12500,
      "eventsRemaining": 37500,
      "resetDate": "2025-02-01T00:00:00Z"
    }
  }
}

Response Fields

Period

Field	Type	Description
`start`	string	Period start (ISO 8601)
`end`	string	Period end (ISO 8601)
`granularity`	string	Data point resolution

Usage - Events

Field	Type	Description
`total`	number	Total events received
`ingested`	number	Successfully ingested events
`duplicates`	number	Deduplicated events
`errors`	number	Events that failed processing
`byType`	object	Event count by type

Usage - Compilations

Field	Type	Description
`total`	number	Compilation runs in period
`artifactsCreated`	number	New artifacts created
`artifactsUpdated`	number	Existing artifacts updated

Usage - Syntheses

Field	Type	Description
`total`	number	Synthesis requests in period
`avgTokensUsed`	number	Average tokens used per synthesis
`avgCompressionRatio`	number	Average compression ratio

Quota

Field	Type	Description
`plan`	string	Current plan name
`eventsLimit`	number	Monthly event limit
`eventsUsed`	number	Events used in current billing period
`eventsRemaining`	number	Remaining events
`resetDate`	string	When the quota resets (ISO 8601)

Plan Quotas

Plan	Monthly Events	Rate Limit
Free	1,000	60/min
Developer	50,000	600/min
Pro	500,000	3,000/min
Enterprise	Unlimited	Unlimited

SDK Examples

TypeScript

const metrics = await hx.getMetrics({ period: '24h' });

console.log(`Events: ${metrics.usage.events.total}`);
console.log(`Quota: ${metrics.quota.eventsUsed}/${metrics.quota.eventsLimit}`);
console.log(`Remaining: ${metrics.quota.eventsRemaining}`);

Python

metrics = await hx.get_metrics(period="7d")

print(f"Events this week: {metrics.usage.events.total}")
print(f"Artifacts created: {metrics.usage.compilations.artifacts_created}")