Usage summary

Resource counts (contacts, active users, phone numbers and agents) plus usage billed in the range, grouped by service type at your sub-account prices.

GET https://api.centerfy.ai/webhooks/inbound/analytics/usage

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	Authenticates the request; or use Authorization: Bearer `<key>`.

Query parameters

Name	Type	Required	Default	Description
`from`	`string (YYYY-MM-DD)`	No	—	First day of the range (inclusive, local date). Defaults to 29 days before to (a 30-day range).
`to`	`string (YYYY-MM-DD)`	No	—	Last day of the range (inclusive, local date). Defaults to today. The range can span at most 366 days.
`timezone`	`string`	No	—	IANA time zone for day boundaries, e.g. America/New_York (max 64 characters). Defaults to your company time zone, else UTC.

Example

curl -X GET "https://api.centerfy.ai/webhooks/inbound/analytics/usage" \
  -H "x-api-key: $CENTERFY_API_KEY"

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.analytics.usage();
console.log(result);

centerfy analytics usage

MCP tool: centerfy_analytics_usage (see MCP server)

Response

{
  "status": "success",
  "tz": "America/New_York",
  "from": "2026-09-06",
  "to": "2026-10-05",
  "capped": false,
  "counts": {
    "contacts": 1250,
    "users": 4,
    "phone_numbers": 3,
    "agents": 5
  },
  "total_spend": 96.42,
  "by_service_type": [
    {
      "service_type": "ai_phone_call",
      "records": 310,
      "quantity": 912.5,
      "total": 82.12
    },
    {
      "service_type": "sms",
      "records": 715,
      "quantity": 715,
      "total": 14.3
    }
  ]
}

Errors

400 — if from/to aren’t real YYYY-MM-DD dates, from is after to, the range is over 366 days, or the timezone is unknown.
401 — if unauthenticated.

Notes

counts are current totals, not limited to the range. by_service_type is sorted by total, highest first; quantity and total are rounded to 4 decimal places. Days run from local midnight to midnight in tz. capped is true when a data source exceeded 20,000 rows — narrow the range for exact figures.