Usage Analytics

The Usage API provides analytics for credit consumption, users, assets, and phone activity.

Run Count Semantics

Where a response includes run_count, it represents distinct customer requests, not the number of underlying model or tool operations. One chat turn, workflow run, app run, agent run, or supported API request counts as one run even when several operations are needed to complete it.

Run count measures request volume. Credit totals measure the AI and tool work used to complete those requests, so requests with the same run_count can have different credit totals. Rows from older periods may report run_count: 0 when the source events did not include a run identifier.

Base Endpoint Group

All usage endpoints live under:

/v1/usage/*

Common Query Parameters

Many endpoints share these optional filters:

tenant_ids: one or more tenant IDs (for example tenant_ids=tenant_abc123 or tenant_ids=tenant_abc123,tenant_def456)
preset: 7d, 30d, 90d, billing_period, or custom
start, end: custom datetime range (used with preset=custom)

Endpoints

Daily Usage

GET /v1/usage/daily

Returns daily usage buckets.

Hourly Usage

GET /v1/usage/hourly

Returns hourly usage buckets.

Usage by Source

GET /v1/usage/source

Returns usage grouped by source.

High-Level Summary

GET /v1/usage/high-level

Returns high-level usage summary metrics.

Heatmap

GET /v1/usage/heatmap

Returns average usage in a day/hour heatmap.

Additional query parameter:

timezone (optional, default UTC)

Users Summary

GET /v1/usage/users/summary

Returns user-level usage summary rows.

Additional query parameters:

limit, offset
sort_dir: asc or desc

Users Creations

GET /v1/usage/users/creations

Returns user creation counts for apps/workflows.

Additional query parameters:

app_type: app or workflow
limit, offset
sort_dir: asc or desc

Models Summary

GET /v1/usage/models

Returns usage grouped by model.

Additional query parameters:

limit, offset
sort_dir: asc or desc

Top Assets

GET /v1/usage/assets

Returns most-used assets.

Additional query parameters:

asset_type: app, workflow, agent, or all
limit, offset
sort_dir: asc or desc

Phone Metrics

GET /v1/usage/phone/metrics

Returns aggregate phone usage metrics.

Phone Series

GET /v1/usage/phone/series

Returns phone call series rows.

Earliest Usage Timestamp

GET /v1/usage/earliest

Returns earliest usage timestamp for selected tenants.

Credit Limit / Usage

GET /v1/usage/limit

Returns total credit limit and total credits used.

Per-Entity Usage State

GET /v1/usage/state

Returns per-entity credit position for the current billing month: credits used, aggregate credit limit, percent used, period bounds, and over-limit flag.

Usage Breakdown

GET /v1/usage/breakdown

Returns usage rows grouped by a single dimension.

Required query parameters:

entity_id: a single tenant ID
from, to: ISO-8601 datetimes
group_by: user, feature, model, or day

Optional query parameters:

limit, offset (apply to user and model group_by)
sort_dir: asc or desc

MSP Admin: Tenants

GET /v1/admin/usage/tenants

MSP-admin only. Returns per-tenant credit position for every child of the caller's own MSP.

Query parameters (all optional):

sort_by: pct_used (default), credits_used, or name
sort_dir: asc or desc
limit, offset (cap 100)

MSP Admin: At-Risk Tenants

GET /v1/admin/usage/at-risk

MSP-admin only. Returns the subset of the caller's own MSP's tenants whose percent_used >= threshold_pct, sorted descending by percent_used, paginated.

Query parameters (all optional):

threshold_pct: 0.0–1.0 (default 0.8)
limit: 0–100 (default 20)
offset: ≥ 0 (default 0)

The response includes total_count (the size of the at-risk set before paging), limit, and offset.

Example Request

curl 'https://ai.hatz.ai/v1/usage/high-level?tenant_ids=tenant_abc123&preset=30d' \
  -H 'X-API-Key: $HATZ_API_KEY'

Example Responses

High-Level Summary Response

{
  "active_users": 42,
  "total_apps_built": 18,
  "total_workflows_built": 33,
  "total_workflows_ran": 945,
  "total_apps_ran": 512,
  "total_agent_chats": 1402,
  "chat_engagements": 1276,
  "total_api_calls": 9834
}

Daily Usage Response

{
  "days": [
    {
      "day": "2026-02-14",
      "input_credits": 212.34,
      "output_credits": 189.78,
      "total_credits": 402.12
    },
    {
      "day": "2026-02-15",
      "input_credits": 230.45,
      "output_credits": 208.32,
      "total_credits": 438.77
    }
  ]
}

Users Summary Response

{
  "users": [
    {
      "user_id": "9ff1b8ff-7f6d-42b4-a8f7-5f3eb459e8dc",
      "email": "owner@acme.com",
      "first_name": "Alex",
      "last_name": "Owner",
      "input_credits": 421.09,
      "output_credits": 421.10,
      "total_credits": 842.19,
      "run_count": 127
    }
  ],
  "count": 1,
  "limit": 5,
  "offset": 0
}

Phone Metrics Response

{
  "total_calls": 268,
  "total_minutes": 824.6,
  "avg_minutes": 3.08
}

Credit Limit / Usage Response

{
  "total_credit_limit": 50000,
  "total_credits_used": 13254.22
}

Per-Entity Usage State Response

{
  "entities": [
    {
      "entity_id": "tenant_abc123",
      "credits_used": 13254.22,
      "credit_limit": 50000,
      "percent_used": 0.265,
      "period_start": "2026-05-01T00:00:00+00:00",
      "period_end": "2026-06-01T00:00:00+00:00",
      "is_over_limit": false,
      "free_pool_remaining": null
    }
  ]
}

Usage Breakdown Response

{
  "entity_id": "tenant_abc123",
  "from": "2026-05-01T00:00:00+00:00",
  "to": "2026-05-15T00:00:00+00:00",
  "group_by": "user",
  "rows": [
    {
      "key": "9ff1b8ff-7f6d-42b4-a8f7-5f3eb459e8dc",
      "display_name": "Alex Owner",
      "input": 421.09,
      "output": 421.10,
      "total": 842.19,
      "run_count": 127
    }
  ]
}

MSP Admin Tenants Response

{
  "tenants": [
    {
      "entity_id": "tenant_abc123",
      "name": "Acme",
      "credits_used": 12876.5,
      "credit_limit": 15000,
      "percent_used": 0.858,
      "period_start": "2026-05-01T00:00:00+00:00",
      "period_end": "2026-06-01T00:00:00+00:00",
      "is_over_limit": false
    }
  ],
  "total_count": 14,
  "limit": 20,
  "offset": 0
}

MSP Admin At-Risk Tenants Response

{
  "threshold_pct": 0.8,
  "entities": [
    {
      "entity_id": "tenant_xyz789",
      "name": "Beta Corp",
      "credits_used": 9200.0,
      "credit_limit": 10000,
      "percent_used": 0.92,
      "period_start": "2026-05-01T00:00:00+00:00",
      "period_end": "2026-06-01T00:00:00+00:00",
      "is_over_limit": false
    },
    {
      "entity_id": "tenant_abc123",
      "name": "Acme",
      "credits_used": 12876.5,
      "credit_limit": 15000,
      "percent_used": 0.858,
      "period_start": "2026-05-01T00:00:00+00:00",
      "period_end": "2026-06-01T00:00:00+00:00",
      "is_over_limit": false
    }
  ],
  "total_count": 2,
  "limit": 20,
  "offset": 0
}

Workflows

Admin - User