Insights overview

The Reports › Insights overview: wallet balance, cost per message compared with the previous period of equal length, a daily series (spend, contacts touched, spend per contact, tool uses) and a bookings heatmap.

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

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.
`bookings_by`	`string`	No	`created`	Bucket the bookings heatmap by when appointments were created or when they are scheduled for. One of created, scheduled.

Example

curl -X GET "https://api.centerfy.ai/webhooks/inbound/analytics/overview?bookings_by=created" \
  -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.overview({
  "bookings_by": "created"
});
console.log(result);

centerfy analytics overview '{"bookings_by":"created"}'

MCP tool: centerfy_analytics_overview (see MCP server)

Response

{
  "status": "success",
  "tz": "America/New_York",
  "from": "2026-10-04",
  "to": "2026-10-05",
  "bookings_by": "created",
  "capped": false,
  "wallet": {
    "balance": 42.5,
    "yesterday_end": 45.1
  },
  "cost_per_message": {
    "spend": 1.2,
    "messages": 60,
    "value": 0.02,
    "prev_spend": 0.9,
    "prev_messages": 50,
    "prev_value": 0.018
  },
  "daily": [
    {
      "day": "2026-10-04",
      "spend_total": 3.1,
      "contacts_touched": 12,
      "spend_per_contact": 0.2583,
      "tool_uses": 8
    },
    {
      "day": "2026-10-05",
      "spend_total": 0,
      "contacts_touched": 0,
      "spend_per_contact": null,
      "tool_uses": 0
    }
  ],
  "tool_uses_total": 8,
  "bookings_total": 3,
  "heatmap": [
    {
      "dow": 1,
      "hour": 10,
      "count": 2
    },
    {
      "dow": 3,
      "hour": 15,
      "count": 1
    }
  ]
}

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

daily has one entry per day in the range. Money values are rounded to 4 decimal places; value, prev_value and spend_per_contact are null when there is nothing to divide by. wallet.yesterday_end is the balance at the end of yesterday (null if unknown). Message spend covers SMS, email, WhatsApp, Facebook and Instagram; messages counts agent-sent messages. heatmap lists only non-empty cells: dow is the ISO weekday (1 = Monday … 7 = Sunday) and hour is the local hour 0–23; cancelled appointments are counted. 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.