API de facturation

Récupérez l'usage et le coût de votre propre workspace dans vos propres systèmes, sans ouvrir la console. Une clé de facturation est un en lecture seule identifiant limité à un seul workspace - elle peut lire les données de facturation, rien de plus.

Créer une clé de facturation

1. Ouvrez Console → Clés d'API de facturation (propriétaire du workspace uniquement). Nommez-la, restreignez-la éventuellement à une liste blanche d'IP ou définissez une expiration, puis copiez la clé - elle commence par sk-syn-bill- et ne s'affiche qu'une seule fois.
2. Appelez les endpoints ci-dessous en l'utilisant comme jeton Bearer. Révoquez-la à tout moment depuis la même page - la révocation l'invalide immédiatement et n'affecte rien d'autre dans le workspace.
3. Une clé est liée à son créateur : s'il n'est plus le propriétaire du workspace, elle cesse de fonctionner et renvoie 403 key_owner_not_authorized.

Authentification

Chaque appel nécessite Authorization: Bearer sk-syn-bill-... envoyé à l'URL de base ci-dessous. Une clé de facturation ne fonctionne que sur ces endpoints, et ces endpoints n'acceptent qu'une clé de facturation - toute autre combinaison renvoie 401 wrong_key_kind.

Authorization: Bearer sk-syn-bill-...

URL de base: https://synthorai.io/api/v1/billing

GET /usage - usage agrégé

GET /usage

Des lignes pré-agrégées par heure ou par jour - pour la facturation et les tableaux de bord. Elles viennent de l'agrégat horaire, complété des requêtes écrites depuis sa dernière ingestion, si bien que les buckets récents n'ont pas un cycle d'ingestion entier de retard.

Dans chaque ligne, api_key_id et api_key_name n'apparaissent que lorsque group_by inclut api_key, et model uniquement lorsqu'il inclut model. avg_latency_ms peut être null quand un bucket n'a aucun échantillon de latence.

Exemple de requête

curl "https://synthorai.io/api/v1/billing/usage?start=2026-09-01&end=2026-09-24&granularity=day" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemple de réponse

{
  "data": [
    {
      "bucket_start": "2026-09-23T00:00:00Z",
      "bucket_end": "2026-09-24T00:00:00Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "requests": 1280,
      "success_requests": 1265,
      "error_requests": 15,
      "errors_4xx": 12,
      "errors_429": 2,
      "errors_5xx": 1,
      "prompt_tokens": 512000,
      "completion_tokens": 98000,
      "cached_tokens": 210000,
      "cache_write_tokens": 8000,
      "reasoning_tokens": 4000,
      "cost_usd": 4.1732,
      "byok_list_price_usd": 0,
      "byok_requests": 0,
      "avg_latency_ms": 812,
      "final": true
    }
  ],
  "meta": {
    "generated_at": "2026-09-24T08:00:00Z",
    "data_complete_until": "2026-09-24T06:00:00Z",
    "timezone": "UTC",
    "currency": "USD",
    "next_cursor": null,
    "has_more": false
  }
}

GET /records - lignes par requête

GET /records

Une ligne par requête, destinée à une synchronisation incrémentale vers votre propre base de données. Synchronisez par cursor, jamais par le temps, et dédupliquez les lignes reçues par record_id - voir "Éviter les trous temporels" ci-dessous pour la raison.

Exemple de requête

curl "https://synthorai.io/api/v1/billing/records?start=2026-09-24T00:00:00Z&limit=500" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemple de réponse

{
  "data": [
    {
      "record_id": "rec_8f2a91c4",
      "request_id": "req_9f3c2b1a",
      "recorded_at": "2026-09-24T05:58:31Z",
      "completed_at": "2026-09-24T05:58:29Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "status": "success",
      "status_code": 200,
      "prompt_tokens": 812,
      "completion_tokens": 194,
      "cached_tokens": 512,
      "cache_write_tokens": 64,
      "cache_write_5m_tokens": 64,
      "cache_write_1h_tokens": 0,
      "cost_usd": 0.00412,
      "byok_list_price_usd": 0,
      "is_byok": false,
      "is_stream": true,
      "duration_ms": 1340,
      "ttft_ms": 210
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjoiODgxNDA5MCJ9",
    "has_more": false,
    "window_final": true,
    "safe_until": "2026-09-24T05:58:31Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "data_complete_until": "2026-09-24T05:58:00Z"
  }
}

GET /records/export - export en flux

GET /records/export

Mêmes filtres que /records, diffusés en JSON délimité par des retours à la ligne (application/x-ndjson) - conçu pour un grand rattrapage plutôt qu'une liste paginée. Un seul export peut être diffusé par workspace à la fois ; un second reçoit 429 too_many_concurrent_requests.

Exemple de requête

curl -N "https://synthorai.io/api/v1/billing/records/export?cursor=eyJvIjoiODgxNDAzMiJ9" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemple de réponse

{"record_id":"rec_8f2a91c4","request_id":"req_9f3c2b1a","model":"claude-sonnet-5","status":"success","cost_usd":0.00412}
{"record_id":"rec_8f2a91c5","request_id":"req_9f3c2b1b","model":"claude-sonnet-5","status":"success","cost_usd":0.00398}
{"_meta":{"next_cursor":"eyJvIjoiODgxNDA5MSJ9","rows":2,"complete":true,"window_final":true,"generated_at":"2026-09-24T06:00:02Z"}}

La dernière ligne du flux est un _meta objet :

GET /summary - statistiques préliminaires et anomalies

GET /summary

Totaux, meilleurs modèles et meilleures clés par coût, et un taux d'erreur pour la plage, plus une anomalies liste (high_error_rate, rate_limited, data_not_final, rollup_delayed), chacune portant une gravité info ou warning et un message lisible. Les chiffres d'une plage non finalisée peuvent encore changer - voir plus bas.

models_count et keys_count donnent les totaux derrière top_models et top_keys, qui ne listent que les 20 premiers par coût au maximum. La plage est par défaut les 30 jours avant end lorsque start est omis.

Exemple de requête

curl "https://synthorai.io/api/v1/billing/summary?start=2026-09-17&end=2026-09-24" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemple de réponse

{
  "data": {
    "totals": { "requests": 48210, "cost_usd": 132.55, "error_rate": 0.021 },
    "models_count": 6,
    "keys_count": 3,
    "top_models": [ { "model": "claude-sonnet-5", "cost_usd": 88.10, "byok_list_price_usd": 0 } ],
    "top_keys": [ { "api_key_id": 42, "api_key_name": "prod-backend", "cost_usd": 61.30, "byok_list_price_usd": 0 } ],
    "anomalies": [
      { "type": "data_not_final", "severity": "info", "message": "The last 2 hours of this range are not yet final." }
    ]
  },
  "meta": {
    "generated_at": "2026-09-24T06:00:02Z",
    "data_complete_until": "2026-09-24T04:00:00Z"
  }
}

GET /freshness - degré de complétude des données

GET /freshness

Renvoie data_complete_until, latest_recorded_at, safe_until et pipeline_lag_seconds - interrogez-le avant de considérer une plage tout juste récupérée comme définitive. safe_until est le recorded_at le plus récent qu'un appelant peut considérer comme complet ; des lignes plus récentes peuvent encore arriver.

Exemple de requête

curl "https://synthorai.io/api/v1/billing/freshness" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemple de réponse

{
  "data": {
    "data_complete_until": "2026-09-24T04:00:00Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "safe_until": "2026-09-24T05:58:31Z",
    "pipeline_lag_seconds": 47
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z" }
}

GET /balance - ce que l'espace de travail peut dépenser maintenant

GET /balance

Renvoie le solde disponible actuel de l'espace de travail - le même montant que dans la console. Conçu pour l'interrogation périodique : toutes les 30 à 60 secondes suffisent. Il a sa propre limite de débit, donc l'interroger n'entame pas le budget des endpoints de données, et il répond même quand le solde est à zéro.

Exemple de requête

curl "https://synthorai.io/api/v1/billing/balance" \
  -H "Authorization: Bearer sk-syn-bill-..."

Exemple de réponse

{
  "data": {
    "available_usd": 1284.37,
    "debt_usd": 0,
    "source": "live",
    "voucher": null,
    "scheduled_credits": [
      { "amount_usd": 250, "release_at": "2026-10-01T00:00:00Z" }
    ],
    "scheduled_credit_total_usd": 250
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z", "currency": "USD" }
}

Erreurs

Chaque erreur est {"error": {"type", "message", "hint"}}:

{
  "error": {
    "type": "range_too_large",
    "message": "the requested range exceeds this endpoint's cap",
    "hint": "narrow start/end to at most 31 days, or sync /records with a cursor instead"
  }
}

Limites de débit et plafonds

Jamais renvoyé : channel_id, upstream_request_id, usage_raw, other, content, ip_address, user_agent, cost_detail.

Éviter les trous temporels

Les requêtes sont écrites dans le log de façon asynchrone après leur fin (quelques secondes normalement, plus en cas de retard accumulé), et le rollup horaire lu par /usage et /summary est ingéré par lots. Les heures les plus récentes sont toujours un peu incomplètes. /usage et /summary ajoutent aussi les requêtes écrites depuis la dernière ingestion (meta.live_tail vaut true) ; si l'agrégat a trop de retard pour cela, meta.live_tail vaut false et les buckets récents sont partiels.

data_complete_until est le plus tôt des deux points suivants : le filigrane du rollup horaire moins son retard de pipeline actuel, ou la requête la plus ancienne pas encore intégrée au rollup - moins une marge de sécurité de 30 minutes, arrondi à l'heure inférieure.

Chaque ligne de /usage porte un indicateur final : true , vrai dès que son bucket se termine avant ou à data_complete_until (valeur renvoyée par /freshness). Un bucket final ne change plus jamais.

• Agrégats: upsertez chaque ligne dans votre propre stockage selon (bucket_start, api_key_id, model), et récupérez à nouveau tout bucket tant qu'il est final: false. Ne calculez jamais un delta en soustrayant un ancien total d'un nouveau.
• Lignes brutes: synchronisez par cursor, jamais par le temps. Conservez next_cursor et reprenez à partir de là au prochain appel, et dédupliquez les lignes reçues par record_id (un id opaque stable par ligne) au cas où une page reprise redélivrerait la même ligne. Les lignes de moins d'environ 5 minutes sont retenues - safe_until est l'heure de la ligne la plus récemment enregistrée moins 5 minutes - si bien qu'une ligne encore en cours d'écriture ne peut jamais se glisser avant une position de curseur déjà distribuée, et rien ne tombe dans un trou. Pour compter les requêtes, comptez les request_id distincts.
• Plage bornée: si vous interrogez une plage start/end au lieu de synchroniser par cursor, ne la considérez complète que lorsque window_final est true (il n'est true que si vous avez fourni un end et qu'il est à ou avant safe_until). Si window_final est false, rappelez plus tard avec la même plage, ou passez à une synchronisation par cursor. Une fenêtre doit commencer au plus tard à safe_until ; un début plus tardif renvoie 400 start_too_recent avec un en-tête Retry-After.

Intégration recommandée

• Facturation nocturne: appelez /usage une fois par jour avec granularity=day, et récupérez à nouveau tout bucket que votre dernière exécution voyait encore comme final: false.
• Détail par requête: appelez /records chaque heure avec cursor réglé sur le dernier next_cursor que vous avez stocké, continuez à paginer tant que has_more est true, et dédupliquez les lignes reçues par record_id.
• Tableaux de bord: appelez /summary pour la plage visible plutôt que d'agréger /records vous-même - elle porte déjà la liste des anomalies.

Besoin de générer ou de gérer des clés API classiques par programmation plutôt que de lire des données de facturation ? Voir Clés de provisioning.