Kullanım API'si

GET /v1/usage, Authorization başlığında yer alan API anahtarı için toplam token ve maliyet değerlerini döndürür. Gün veya saat bazında gruplayabilir, isteğe bağlı olarak modele göre ayırabilirsiniz. Başka bir anahtarın verilerini okumak mümkün değildir — bunun için panele giriş yapın.

Kimlik doğrulama

Kullanımını okumak istediğiniz Kunavo API anahtarını Bearer token olarak iletin. Uç nokta, yalnızca bu belirli anahtara faturalandırılan kullanımı döndürür — başka bir anahtarın verilerini istemek için herhangi bir parametre yoktur.

İstek

Örnekler

Son 30 günün günlük toplamları, tüm modeller bir arada:

# Daily totals for the last 30 days
curl https://api.kunavo.com/v1/usage \
  -G \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  --data-urlencode "start_date=2026-04-28" \
  --data-urlencode "end_date=2026-05-27"

(Gün, model) başına bir satır:

# Per-model daily breakdown — one row per (day, model)
curl https://api.kunavo.com/v1/usage \
  -G \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  --data-urlencode "start_date=2026-05-01" \
  --data-urlencode "end_date=2026-05-27" \
  --data-urlencode "group_by=model"

Python — aralıktaki değerleri tek bir sayıda toplama:

import os, datetime as dt, requests

today = dt.date.today()
start = today - dt.timedelta(days=29)  # last 30 days inclusive

r = requests.get(
    "https://api.kunavo.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['KUNAVO_API_KEY']}"},
    params={
        "start_date": start.isoformat(),
        "end_date":   today.isoformat(),
        "group_by":   "model",
    },
    timeout=30,
)
r.raise_for_status()
body = r.json()

# body["data"] is one row per (day, model). Sum cost across the window:
total_usd = sum(float(row["cost_usd"]) for row in body["data"])
print(f"Spent ${total_usd:.4f} on key {body['api_key']['name']}")

Yanıt

200 OK — satır listesi içeren application/json. Etkinlik olmayan aralıklar atlanır; kesintisiz bir dizi gerekiyorsa eksik aralıkları istemci tamamlar.

{
  "object": "list",
  "api_key": {
    "id": "k_abc123",
    "name": "production",
    "prefix": "sk-kn-aZ8x"
  },
  "start_date": "2026-05-01",
  "end_date":   "2026-05-27",
  "bucket": "day",
  "data": [
    {
      "bucket_start": "2026-05-01T00:00:00.000Z",
      "model": "claude-sonnet-4-6",
      "requests": 1284,
      "errors": 7,
      "input_tokens": 1532890,
      "output_tokens": 245100,
      "cached_input_tokens": 980000,
      "cache_write_tokens": 12000,
      "web_search_requests": 0,
      "cost_usd": "3.452100"
    },
    {
      "bucket_start": "2026-05-01T00:00:00.000Z",
      "model": "gpt-5",
      "requests": 88,
      "errors": 0,
      "input_tokens": 42000,
      "output_tokens": 12300,
      "cached_input_tokens": 0,
      "cache_write_tokens": 0,
      "web_search_requests": 0,
      "cost_usd": "0.210400"
    }
  ]
}

İstemci tarafında önbelleğe alma

Uç nokta Cache-Control: private, max-age=60 üst bilgisini ayarlar. Çoğu istemci (tarayıcılar, oturum içeren istekler ve tarafınızdaki tüm HTTP önbellekleri), aynı parametrelerle yapılan isteklerin yanıtını 60 saniyelik bir aralıkta yeniden kullanır — bu, düzenli aralıklarla sorgulama yapan panolar için uygundur. Güncel bir yanıt almak için sorgu dizesini değiştirin (ör. bir &_=tsbustera ekleyin) veya kendi tarafınızda Cache-Control: no-cache gönderin.

Hatalar

Dikkat edilmesi gerekenler

• Silinen anahtarlar. Bir API anahtarını iptal ettiğinizde, geçmiş kullanım satırlarındaki api_key_id alanı (null olarak ayarlanır) silinir; bu nedenle geçmiş toplamlar bu uç nokta üzerinden artık alınamaz. Veriler, paneldeki hesabınızın toplam görünümünde kalmaya devam eder. Değiştirilemez bir anahtar başına denetim kaydına ihtiyacınız varsa iptal etmeden önce verileri alıp saklayın.
• Gerçek zamana yakın. Satırlar, ilgili çağrı tamamlandıktan birkaç saniye içinde eklenir. Gecikme için garanti edilmiş bir üst sınır yoktur — faturanızla tam eşleşme gerekiyorsa dakika dakika sorgulamak yerine her gün bir önceki günün verilerini sorgulayın.
• Maliyet, faturalandırılan tutardır. Buradaki cost_usd, cüzdan defterinizden düşülen tutarla aynıdır. Bu tutar, Faturalandırma bölümünde açıklanan max(catalog, upstream × markup) alt sınırını zaten yansıtır. Bu yanıtta ayrı bir "toptan satış" tutarı bulunmaz.

Sonraki adımlar

• Faturalandırma ve defter — her çağrı için cost_usd değerinin buraya yansımadan önce nasıl hesaplandığı.
• Kimlik doğrulama — yeni API anahtarları oluşturma (proje başına bir tane).
• Panel kullanım görünümü — aynı verileri grafiklerle, çağrı başına ayrıntılarla ve tüm anahtarlarınızdaki hesap genelindeki toplamlarla sunar.