Consum

2 endpoint-uri. Fiecare cale de mai jos este relativă la URL-ul de bază al API-ului și include deja prefixul /api/v1 — vezi convențiile pentru autentificare, paginare, erori și idempotență.

	Endpoint
GET	/billing/usage	List raw usage events for a period with provider cost, platform fee, customer charge and margin
GET	/billing/usage/summary	Summarise usage for a period grouped by component, provider, model or call with cost and margin totals

Endpoint-uri

List raw usage events for a period with provider cost, platform fee, customer charge and margin

GET/billing/usage

• Necesită billing.read.
• Defaults to the last 30 days; component, provider, model, call_id, campaign_id and assistant_id accept repeated values. Malformed from/to yields a 500, not a 422.

cURL

curl -X GET "$CALLAGENT_API_URL/billing/usage" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

JavaScript

const response = await fetch(`${process.env.CALLAGENT_API_URL}/billing/usage`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

PHP

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/billing/usage');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

Python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/billing/usage",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
200	data-wrapped array

Erori

Status	Când apare
403	Neither the API key scope nor the session user's permission allows billing.read

Exemplu de răspuns, generat din schemă:

{
  "data": [
    {
      "id": null,
      "call_id": "01JQ0000000000000000000000",
      "component": "string",
      "provider": "string",
      "model": "string",
      "billing_mode": "string",
      "quantity": "string",
      "unit": "string",
      "billable_units": "string",
      "currency": "string",
      "provider_cost": "string",
      "platform_fee": "string",
      "customer_charge": "string",
      "margin": "string",
      "is_free": true,
      "occurred_at": "2026-01-01T12:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1,
    "from": "+40712345678",
    "to": "+40712345678"
  }
}

Summarise usage for a period grouped by component, provider, model or call with cost and margin totals

GET/billing/usage/summary

• Necesită billing.read.
• An unrecognised by value silently falls back to component instead of failing. Malformed from/to yields a 500, not a 422.

Parametri de interogare

Nume	Tip	Obligatoriu	Note
by	string	—

cURL

curl -X GET "$CALLAGENT_API_URL/billing/usage/summary?by=string" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

JavaScript

const response = await fetch(`${process.env.CALLAGENT_API_URL}/billing/usage/summary?by=string`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

PHP

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/billing/usage/summary?by=string');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

Python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/billing/usage/summary?by=string",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Răspunsuri

Status	Corp
200	data-wrapped array

Erori

Status	Când apare
403	Neither the API key scope nor the session user's permission allows billing.read

Exemplu de răspuns, generat din schemă:

{
  "data": [
    "string"
  ],
  "meta": {
    "by": "string",
    "from": "+40712345678",
    "to": "+40712345678"
  }
}