Usage Analytics

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

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 an MSP entity.

Required query parameters:

msp_entity_id: MSP entity ID (must match the caller's managed_entity_id)

Optional query parameters:

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 tenants whose percent_used >= threshold_pct, sorted descending by percent_used, paginated.

Required query parameters:

msp_entity_id

Optional query parameters:

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