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.

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
}

Workflows

Admin - User