API Reference

Usage

Query call minutes, costs, and SMS usage over any date range. Supports daily, weekly, and monthly granularity with optional per-agent breakdown.

Scoping

A sfy_live_* project key returns usage for that project only. To query across all projects in your organization, use a sfy_org_* org key and omit the X-Project-Id header. To query a specific project with an org key, include X-Project-Id: proj_abc123 in the request.

GET/v1/usage

Param	Default	Description
from	30 days ago	Start date (YYYY-MM-DD)
to	today	End date (YYYY-MM-DD, max 366 days range)
granularity	day	day \| week \| month
agent_id	—	Filter to one agent's data only
breakdown	—	Set to "agent" to add by_agent array (top 20 agents)

week granularityEach bucket date is the Monday that starts that ISO week (e.g. a call on Wednesday 2026-01-07 appears under 2026-01-05).

missed_callsCounts calls with status busy, no-answer, canceled, or rejected.

avg_duration_secondsAveraged over completed calls only (duration_seconds > 0). Returns 0 if no qualifying calls exist.

max rangefrom and to cannot span more than 366 days. The endpoint returns 400 if exceeded.

Response structure

{
  "from": "2026-01-01",
  "to":   "2026-01-31",
  "granularity": "day",
  "summary": {
    "total_calls":          1240,
    "total_minutes":        2544.2,
    "total_cost":           559.72,
    "call_cost":            559.72,
    "recording_cost":       0.0,
    "transfer_cost":        12.5,
    "llm_discount":         0.0,
    "sms_count":            890,
    "sms_cost":             44.5,
    "grand_total_cost":     604.22,
    "completed_calls":      1198,
    "failed_calls":         12,
    "missed_calls":         30,
    "transferred_calls":    45,
    "avg_duration_seconds": 122.7
  },
  "timeseries": [
    {
      "date":               "2026-01-01",
      "calls":              42,
      "minutes":            87.4,
      "total_cost":         19.23,
      "call_cost":          18.50,
      "recording_cost":     0.0,
      "transfer_cost":      0.73,
      "llm_discount":       -0.12,
      "avg_duration_seconds": 124.8,
      "sms_count":          28,
      "sms_cost":           1.4
    }
  ],
  "by_agent": [   // only when breakdown=agent
    {
      "agent_id":      "agent_28c51f81",
      "agent_name":    "Nova Insurance",
      "calls":         890,
      "minutes":       1850.2,
      "total_cost":    407.04,
      "completed_calls": 872
    }
  ]
}

Examples

curl "https://api.staffifyai.com/v1/usage" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

January by week, with per-agent breakdown

curl "https://api.staffifyai.com/v1/usage?from=2026-01-01&to=2026-01-31&granularity=week&breakdown=agent" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

One agent, daily

curl "https://api.staffifyai.com/v1/usage?agent_id=agent_28c51f81&granularity=day" \
  -H "Authorization: Bearer sfy_live_YOUR_KEY"

Node.js: last calendar month report

const now  = new Date();
const from = new Date(now.getFullYear(), now.getMonth() - 1, 1)
  .toISOString().slice(0, 10);
const to   = new Date(now.getFullYear(), now.getMonth(), 0)
  .toISOString().slice(0, 10);

const data = await fetch(
  `https://api.staffifyai.com/v1/usage?from=${from}&to=${to}&granularity=month`,
  { headers: { Authorization: `Bearer ${process.env.STAFFIFY_API_KEY}` } }
).then(r => r.json());

const { summary } = data;
console.log(`Period: ${from} to ${to}`);
console.log(`Calls: ${summary.total_calls} (${summary.total_minutes.toFixed(1)} min)`);
console.log(`SMS: ${summary.sms_count} messages (EUR ${summary.sms_cost.toFixed(2)})`);
console.log(`Total: EUR ${summary.grand_total_cost.toFixed(2)}`);

← Calls Credits →