Usage

Requests, leads, calls, minutes and cost for a month.

Every example sends your key ID and secret as CALLVIEW_KEY_ID and CALLVIEW_SECRET (see Keys and authentication). The base address is https://v2-api.callview.ai/api/v1/external.

Usage for a month

GET /usage

API requests, leads added, calls, billable minutes and their cost for the month so far (or a past month), in your organization’s time zone. Minutes are the bill’s own rule (rounded up per call) and cost_usd is those minutes at your rate, so the month’s total matches your bill. Updated every 5 minutes (updated). A test key sees its test counts (livemode: false, never billed). A key limited to some campaigns sees only their leads, calls and minutes, plus its own requests. Needs the usage:read permission.

Parameters

Name	In	Type	Required	Notes
`period`	query	string		`current` (the month so far) or a month, YYYY-MM. Default `"current"`.
`group_by`	query	string		Split the totals by API key, campaign or day. One of `key` / `campaign` / `day`.

curl -X GET 'https://v2-api.callview.ai/api/v1/external/usage' \
  -u "$CALLVIEW_KEY_ID:$CALLVIEW_SECRET"

const auth = Buffer.from(`${process.env.CALLVIEW_KEY_ID}:${process.env.CALLVIEW_SECRET}`).toString('base64');

const res = await fetch('https://v2-api.callview.ai/api/v1/external/usage', {
  method: 'GET',
  headers: { Authorization: `Basic ${auth}` },
});
console.log(res.status, res.headers.get('request-id'));
console.log(await res.text());

import os

import requests

res = requests.request(
    "GET",
    "https://v2-api.callview.ai/api/v1/external/usage",
    auth=(os.environ["CALLVIEW_KEY_ID"], os.environ["CALLVIEW_SECRET"]),
    timeout=30,
)
print(res.status_code, res.headers.get("Request-Id"))
print(res.text)

<?php
$ch = curl_init('https://v2-api.callview.ai/api/v1/external/usage');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_USERPWD => getenv('CALLVIEW_KEY_ID') . ':' . getenv('CALLVIEW_SECRET'),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER => false,
]);
$body = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), "\n", $body, "\n";

200 The month’s totals, and with group_by one group per key, campaign or day carrying the same counts plus its key_id / key_name, campaign_id / campaign_name, or day.

{
  "data": {
    "object": "usage",
    "period": "2026-10",
    "timezone": "America/New_York",
    "livemode": true,
    "totals": {
      "requests": 1840,
      "leads_added": 212,
      "calls": 260,
      "calls_connected": 141,
      "minutes": 388,
      "cost_usd": 58.2
    },
    "group_by": null,
    "groups": [],
    "updated": "2026-10-06T17:05:00.000Z"
  }
}

Errors

Status	Codes
400	`invalid_request`
401	`authentication_failed`
403	`permission_denied`
429	`rate_limited`, `too_many_concurrent_requests`
500	`internal_error`