# Analitik ve Raporlar API'si

Bu salt okunur uç noktalar, hesabınızın etkinliğini kendi panolarınıza ve raporlarınıza çekmenizi sağlar: mesaj olayı sayıları, kredi tüketimi, yapay zeka harcamaları ve uygulama içi panonun gösterdiği grafikler ve içgörülerin aynısı. Bu kılavuz şunları kapsar:

- **Özet** — mesaj hacmi sayaçları (gönderilen, iletilen, okunan, yanıtlanan, randevu alınan, oluşturulan kişiler, krediler).
- **Krediler** — toplamlar ve dökümlerle birlikte kredi kullanımının ayrıntılı, sayfalandırılmış bir dökümü.
- **Yapay zeka maliyeti** — günlük yapay zeka harcaması toplamı.
- **Metrik serileri** — kampanya, kanal, yapay zeka temsilcisi veya numaraya göre gruplandırılmış, grafik oluşturmaya hazır bir zaman serisi.
- **Konuşma sonuçları** — yapay zeka tarafından atanan sonuç etiketine göre konuşmaların nasıl sona erdiği.
- **Pano içgörüleri** ve **Pano yapay zeka içgörüleri** — yapay zeka tarafından yazılmış özetler dahil olmak üzere, uygulama içi panonun arkasındaki tüm veriler.
- **Varlık etkinliği** — tek bir kişinin, anlaşmanın veya görevin zaman çizelgesi.
- **Toplu olay sayıları** — mevcut entegrasyonlar için tutulan, Özet'in eski, camelCase biçimi.

Bu sayfadaki her uç nokta, her ikisi birden değil, tam bir kapsam gerektirir: uç noktanın kabul ettiği durumlarda `campaign_id` (eski) veya `agent_id` değerlerinden en fazla birini iletin. Her ikisini de göndermek `400` sonucunu döndürür ve hesabınızda bulunmayan bir kimlik, `403` yerine `404` döndürür; böylece diğer hesapların kimlikleri tahmin edilemez kalır.

Aşağıdaki tüm yollar, API temel URL'sine göre belirlenmiştir:

```
https://api.youraiconnector.com/v1
```

Her isteğin kimliği doğrulanmalıdır. Kabul edilen dört yöntem için [Kimlik Doğrulama](authentication.md) bölümüne bakın. Buradaki örnekler `X-API-Key` başlığını (ve cURL için bir sorgu parametresi biçimini) kullanır.

---

## Tarih aralığı

Her üç uç nokta da aynı isteğe bağlı tarih filtrelerini kabul eder:

| Parametre | Açıklama |
|---|---|
| `from` | Aralığın başlangıcı, `YYYY-MM-DD`, dahil. Varsayılan olarak 30 gün öncesidir. |
| `to` | Aralığın sonu, `YYYY-MM-DD`, dahil. Varsayılan olarak bugündür. |

Tarihler UTC olarak yorumlanır. Aralık varsayılan olarak **son 30 gün**dür ve **366 gün** ile sınırlandırılmıştır; daha geniş bir aralık `400` döndürür. `from`, `to` tarihinden sonra olmamalıdır.

### `truncated` bayrağı

**Özet** ve **Krediler** uç noktaları, tek bir isteğin tarayabileceği kayıt sayısını sınırlar. Aralığınız bu sınıra ulaşacak kadar yoğunsa, yanıt `"truncated": true` içerir. Bunu gördüğünüzde, sayılar kısmi bir taramaya dayalıdır; tam rakamları almak için tarih aralığınızı daraltın (veya daha küçük bir pencereyle sayfalar arasında gezinin).

::: note
**Not:** Maliyet ve token rakamları yalnızca kendi sağlayıcı API anahtarlarınız üzerinden faturalandırılan yapay zeka çağrıları için dahil edilir. Hesabınız için maliyet rakamları gizlendiğinde, yanıt `"costs_redacted": true` değerini ayarlar ve maliyet alanları sıfır olarak döndürülür.
:::


---

## Mesaj hacmi özeti

Hesabınız için hem aralık toplamları hem de günlük seri olarak toplanmış mesaj etkinliği sayaçlarını döndürür. Aralıktaki her gün `by_date` içinde görünür; sessiz günler sıfır ile doldurulur. İsteğe bağlı olarak `campaign_id` ile tek bir kampanyaya filtre uygulayın.

`GET /analytics/summary`

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `from` | Hayır | Aralık başlangıcı, `YYYY-MM-DD`. |
| `to` | Hayır | Aralık bitişi, `YYYY-MM-DD`. |
| `campaign_id` | Hayır | Yalnızca bu kampanyaya ait etkinlikleri say. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/summary?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/summary",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total": 1240,
    "sent": 800,
    "delivered": 760,
    "read": 540,
    "replied": 210,
    "booked": 35,
    "contact_created": 120,
    "credits_spent": 412.5,
    "credits_recharged": 500
  },
  "by_date": [
    {
      "date": "2026-05-01",
      "total": 40,
      "sent": 25,
      "delivered": 24,
      "read": 18,
      "replied": 7,
      "booked": 1,
      "contact_created": 4,
      "credits_spent": 13.5,
      "credits_recharged": 0
    }
  ],
  "truncated": false
}
```

`by_date` içindeki her girdi, `totals` ile aynı sayaç alanlarına ve ek olarak bir `date` değerine sahiptir.

Hesabınıza ait olmayan bir `campaign_id` gönderirseniz, yanıt `{ "success": false, "error": "Campaign not found" }` ile birlikte `404` olur.

---

## Kredi kullanımı

Belirtilen aralıktaki kredi kullanımını döndürür: sayfalandırılmış bireysel kayıt listesi ile birlikte aralık toplamları ve neden ile kampanyaya göre dökümler.

`GET /analytics/credits`

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `from` | Hayır | Aralık başlangıcı, `YYYY-MM-DD`. |
| `to` | Hayır | Aralık bitişi, `YYYY-MM-DD`. |
| `campaign_id` | Hayır | Yalnızca bu kampanyaya atfedilen kullanımı dahil et. |
| `limit` | Hayır | `records` için sayfa boyutu, 1–100 arası. Varsayılan değer 50'dir. |
| `cursor` | Hayır | Bir sonraki sayfayı getirmek için önceki sayfanın `next_cursor` değerini gönderin. |

> **Düzeltmeler ve tüketim:** Bonuslar, plan yenilemeleri ve düzeltmeler gibi bakiye değişiklikleri `totals` ve dökümlerden **hariç tutulur**; bunlar gerçek tüketim değildir. Yine de `"is_adjustment": true` ile işaretlenmiş olarak `records` listesinde görünürler.

**Toplamlar ve dökümler yalnızca ilk sayfada görünür** (herhangi bir `cursor` sağlanmadığında). Sonraki sayfalarda `totals`, `by_reason`, `by_reason_cost` ve `by_campaign` değerleri `null` olarak döndürülür; yalnızca `records` dizisi devam eder. Bu, her sayfa için tüm aralığın yeniden taranmasını önler.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/credits?from=2026-05-01&to=2026-05-31&limit=50&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  limit: "50",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/credits?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

// To page: pass data.next_cursor as ?cursor on the next request, until it is null.
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/credits",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31", "limit": 50},
)
data = res.json()

# To page: pass data["next_cursor"] as cursor on the next request, until it is None.
```

**Yanıt** (ilk sayfa)

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "credits_used": 412.5,
    "cost_usd": 1.284512,
    "records": 318
  },
  "by_reason": {
    "AI Message": 380.0,
    "Campaign Message": 32.5
  },
  "by_reason_cost": {
    "AI Message": 1.284512,
    "Campaign Message": 0
  },
  "by_campaign": {
    "Spring Promo": 250.0,
    "Reactivation": 162.5
  },
  "records": [
    {
      "id": "rec_abc123",
      "amount": 1,
      "timestamp": "2026-05-31T14:02:11.000Z",
      "reason": "AI Message",
      "is_adjustment": false,
      "campaign_id": "campaign123",
      "campaign_name": "Spring Promo",
      "contact_id": "contact456",
      "contact_name": "Jane Smith",
      "credit_type": "ai",
      "custom_keys_used": false,
      "description": null,
      "cost_usd": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "cache_read_tokens": 0,
      "cache_creation_tokens": 0,
      "ai_model": null,
      "request_id": null,
      "is_test": false
    }
  ],
  "next_cursor": "rec_abc123",
  "costs_redacted": false,
  "truncated": false
}
```

**Alan notları:**

- `amount` — kayıt için tahsil edilen krediler. Kendi sağlayıcı API anahtarınız üzerinden faturalandırılan kayıtlar için sıfırdır.
- `is_adjustment` — bakiye değişiklikleri için `true` (toplamlardan/dökümlerden hariç tutulur).
- `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens`, `ai_model`, `request_id` — yalnızca kendi sağlayıcı API anahtarınız üzerinden faturalandırılan kayıtlarda doldurulur; aksi takdirde sıfır veya `null` değerini alır.
- `is_test` — asla faturalandırılmayan oyun alanı/test çalışmaları için `true`.
- `next_cursor` — bir sonraki sayfa için imleç veya daha fazla kayıt kalmadığında `null`.

---

## Yapay zeka maliyet özeti

Hesabınız için günlük yapay zeka harcama özetini döndürür. Bu, önceden toplanmış günlük toplamları okur, bu nedenle uzun aralıklarda bile hızlıdır. Aralıktaki her gün `days` içinde görünür; işlem yapılmayan günler sıfır ile doldurulur.

`GET /analytics/ai-cost`

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `from` | Hayır | Aralık başlangıcı, `YYYY-MM-DD`. |
| `to` | Hayır | Aralık bitişi, `YYYY-MM-DD`. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/ai-cost?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/ai-cost?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/ai-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "totals": {
    "total_usd": 12.4821,
    "byok_usd": 12.4821,
    "platform_usd": 0,
    "calls": 4210
  },
  "days": [
    {
      "date": "2026-05-01",
      "total_usd": 0.4012,
      "byok_usd": 0.4012,
      "platform_usd": 0,
      "input_usd": 0.18,
      "output_usd": 0.19,
      "cache_creation_usd": 0.02,
      "cache_read_usd": 0.0112,
      "calls": 140,
      "by_provider": { "anthropic": 0.4012 }
    }
  ],
  "costs_redacted": false
}
```

**Alan notları:**

- `byok_usd` — kendi sağlayıcı API anahtarlarınız üzerinden faturalandırılan harcama.
- `platform_usd` — kendi anahtarınız yerine platform üzerinde çalışan harcama kısmı.
- `input_usd`, `output_usd`, `cache_creation_usd`, `cache_read_usd` — `total_usd`'yı oluşturan maliyet bileşenleri.
- `by_provider` — AI sağlayıcı adına göre anahtarlanmış USD harcaması.
- USD rakamları yalnızca kendi sağlayıcı anahtarını kullanan hesaplara döndürülür. Kredi ile ödeme yapan hesaplar için her USD alanı sıfırdır ve `costs_redacted` değeri `true`'dur (çağrı sayıları görünür kalır).

---

## Metrik serileri

Tek bir çağrıda bir veya daha fazla metrik zaman serisi döndürür, isteğe bağlı olarak iki boyuta kadar gruplandırılabilir — bir grafiği bağlamak için kullanılan uç nokta. Tek bir istek, kampanya başına bir çağrı yapmadan "bu kampanya için kanal başına, günlük gönderilen ve yanıtlanan" sorusunu yanıtlayabilir.

`GET /analytics/series`

Her yanıt bir `labels` dizisi (zaman ekseni, tüm aralık boyunca sıfırlarla doldurulmuş) ve `series` içinde grup başına bir girdi taşır; her biri `labels` ile hizalanmış, istenen metrik başına bir dizi tutar. `limit` sonrasındaki seriler atılmaz; bunlar, toplam aralıktan döndürülen serinin çıkarılmasıyla hesaplanan `other_bucket` içinde toplanır, böylece oluşturulan bir grafik her zaman gerçek sayılarınızla eşleşir; bu durum gerçekleştiğinde `truncated`, `true` değerini alır.

Sayıların kaynağı: `sent`, `delivered`, `read` ve `replied`, kanal ve gönderen numarayı taşıyan mesaj kayıtlarından gelir. `booked`, `contact_created` ve `credits_spent`, gönderen numarası taşımayan olay akışından gelir, bu nedenle `number`'e göre gruplandırma yaptığınızda bu metrikler `null` numaralı kovaya düşer.

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `from` | Hayır | Aralık başlangıcı, `YYYY-MM-DD`. Varsayılan olarak 30 gün öncesidir. |
| `to` | Hayır | Aralık sonu, `YYYY-MM-DD`. Varsayılan olarak bugündür. |
| `metrics` | Hayır | `sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent` arasından virgülle ayrılmış liste. Varsayılan olarak `sent,replied`. Bilinmeyen bir metrik `400` döndürür. |
| `group_by` | Hayır | `date`, `campaign`, `channel`, `agent`, `number` arasından iki boyuta kadar virgülle ayrılmış liste. `date` kabul edilir ancak bir etkisi yoktur; her yanıt zaten zaman eksenini taşır. Hesap genelinde tek bir seri için atlayın. |
| `granularity` | Hayır | `day` (varsayılan), `week` veya `month`. Hafta kovaları Pazartesi günü, ay kovaları 1. günde başlar. |
| `limit` | Hayır | Geri kalanlar `other_bucket` içinde toplanmadan önce döndürülecek seri sayısı, 1–50. Varsayılan olarak 12. |
| `campaign_id` | Hayır | Yalnızca bu kampanyaya ait etkinlikleri sayın. Eski; `agent_id` tercih edin. |
| `agent_id` | Hayır | Yalnızca bu yapay zeka temsilcisine ait etkinlikleri sayın. |
| `channel` | Hayır | Yalnızca bu kanaldaki etkinlikleri sayın, örneğin `whatsapp`. |

Bu uç noktanın tarih aralığı **92 gün** ile sınırlandırılmıştır (bu sayfada başka yerlerde kullanılan 366 günlük sınırdan daha dardır).

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/series?from=2026-05-01&to=2026-05-31&metrics=sent,replied,booked&group_by=campaign,channel&limit=10&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  metrics: "sent,replied,booked",
  group_by: "campaign,channel",
  limit: "10",
});
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/series?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/series",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "from": "2026-05-01",
        "to": "2026-05-31",
        "metrics": "sent,replied,booked",
        "group_by": "campaign,channel",
        "limit": 10,
    },
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "granularity": "day",
  "labels": ["2026-05-01", "2026-05-02"],
  "group_by": ["campaign", "channel"],
  "metrics": ["sent", "replied", "booked"],
  "series": [
    {
      "key": {
        "campaign_id": "campaign123",
        "campaign_name": "Spring Promo",
        "channel": "whatsapp"
      },
      "total": 812,
      "metrics": {
        "sent": [40, 35],
        "replied": [12, 9],
        "booked": [2, 1]
      }
    }
  ],
  "other_bucket": {
    "series_count": 6,
    "total": 340,
    "metrics": {
      "sent": [18, 20],
      "replied": [5, 6],
      "booked": [0, 1]
    }
  },
  "truncated": true
}
```

**Alan notları:**

- `key` — bir serinin kimliği. Yalnızca istenen `group_by` boyutlarına ait anahtarlar mevcuttur; bir satır için değeri bilinmeyen bir boyut (kampanyası olmayan bir mesaj, kanalı olmayan bir olay), atılmak yerine `null` olarak geri döner, böylece seriler toplamlarla eşleşmeye devam eder.
- `other_bucket` — hiçbir şey toplanmadığında `null`.
- Bu uç nokta, raporlama veritabanı hesabınız için yanıt veremediğinde, sıfırlarla dolu bir `200` yerine `"error_code": "analytics_unavailable"` ile `503` döndürür; sıfırlanmış bir grafik gerçek gibi okunabilir.

---

## Konuşma sonuçları

Konuşmaların bir tarih aralığında nasıl sona erdiğini döndürür: yapay zekanın atadığı her sonuç etiketi için günlük bir sayı, ayrıca yanıtlar, randevular, bir insana devretmeler ve yapay zekanın asla sınıflandırmadığı konuşmalar için aralık toplamları.

`GET /analytics/outcomes`

Zaman eksenini daraltmak ve yalnızca etiket başına aralık toplamlarını almak için `group_by=tag` değerini iletin; bu modda `labels` boştur ve her etiketin `counts` dizisi boştur, ancak `total` hala doldurulmuştur.

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `from` | Hayır | Aralık başlangıcı, `YYYY-MM-DD`. Varsayılan olarak 30 gün öncesidir. |
| `to` | Hayır | Aralık bitişi, `YYYY-MM-DD`. Varsayılan olarak bugündür. |
| `campaign_id` | Hayır | Yalnızca şu anda bu kampanyada olan kişilerle yapılan görüşmeleri sayar. Eski; `agent_id` tercih edin. |
| `agent_id` | Hayır | Yalnızca bu Yapay Zeka Temsilcisine ait sonuçları sayar. |
| `group_by` | Hayır | `date` (varsayılan) günlük sayıları tutar; `tag` aralık toplamlarına indirger. |

Bu uç noktanın tarih aralığı **92 gün** ile sınırlandırılmıştır.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/outcomes?from=2026-05-01&to=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ from: "2026-05-01", to: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/outcomes?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/outcomes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"from": "2026-05-01", "to": "2026-05-31"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "from": "2026-05-01",
  "to": "2026-05-31",
  "group_by": "date",
  "labels": ["2026-05-01", "2026-05-02"],
  "by_tag": [
    { "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}
```

**Alan notları:**

- `by_tag[].tag` — Yapay zekanın hiçbir sonuç etiketi atamadığı görüşmeler için `null`.
- `totals.human_alerted` — bir insana devredilen görüşmeler; bu, her devirde yazılır ve daha önce hiçbir uç nokta tarafından sunulmamıştır.
- Raporlama veritabanı yanıt veremediğinde Metrik serisi ile aynı `503`/`analytics_unavailable` duruşu.

---

## Gösterge paneli içgörüleri

Tek bir çağrıda bir tarih aralığı için tam gösterge paneli yükünü döndürür: hafta içi ve saate göre yanıt oranı ısı haritası, kampanya liderlik tablosu, kanal başına hacim, bağlantı başına kesin toplamlar, günlük metrik dökümleri (hesap genelinde, kanal başına ve numara başına), kişilerin nereden geldiği, gelen kutusu yanıt süresi ve son etkinlik akışı. Bu, API'deki en zengin raporlama yüküdür; doğrudan uygulama içi gösterge paneline güç sağlar.

`GET /analytics/dashboard-insights`

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `startDate` | Evet | Aralık başlangıcı, `YYYY-MM-DD`. |
| `endDate` | Evet | Aralık bitişi, `YYYY-MM-DD`. |
| `campaignId` | Hayır | Yalnızca bu kampanyaya ait etkinlikleri dahil et (`campaign_id` de kabul edilir). Eski; `agent_id` tercih edin. |
| `agent_id` | Hayır | Yalnızca bu Yapay Zeka Temsilcisine ait etkinlikleri dahil et (`agentId` de kabul edilir). Bir temsilci kapsamı altında, kampanya liderlik tablosu yalnızca o temsilcinin etkinliğinden oluşturulur. |

Bu uç nokta `startDate`/`endDate` kullanır ( `from`/`to` değil), çünkü uygulamasını uygulama içi gösterge paneli ile paylaşır. Aralık 92 gün ile sınırlandırılmıştır ve daha geniş olduğunda **reddedilmez, kırpılır**.

> **Null, sıfır değil, kullanılamaz anlamına gelir.** Birkaç blok (`numberStats`, `channelDailySeries`, `metricDailyBreakdown`, `contactsByCountry`) raporlama veritabanından hesaplanır ve hesabınız için yanıt veremediğinde `null` olarak döner. Bir `null` bloğunu boş bir grafik olarak oluşturmayın.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/dashboard-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()
```

**Yanıt** (kısaltılmış — bu yük büyüktür; tam şema için [API Referansına](reference.md) bakın)

```json
{
  "success": true,
  "data": {
    "heatmap": {
      "buckets": [
        { "weekday": 1, "hour": 9, "sent": 12, "replied": 5, "replyRate": 0.42 }
      ]
    },
    "topCampaigns": [
      { "campaignId": "campaign123", "name": "Spring Promo", "sent": 420, "replied": 180, "booked": 22, "replyRate": 0.43, "creditsSpent": 210.5 }
    ],
    "channelVolume": [
      { "channel": "whatsapp", "sent": 800, "received": 540, "lastMessageAt": "2026-05-31T14:02:11.000Z" }
    ],
    "inboxSla": { "medianFirstResponseMs": 92000, "sampleSize": 140 },
    "activityFeed": [
      { "id": "evt_1", "kind": "booked", "at": "2026-05-31T14:02:11.000Z", "contactId": "contact456", "contactName": "Jane Smith", "campaignId": "campaign123", "campaignName": "Spring Promo", "label": "Jane Smith booked an appointment" }
    ],
    "numberStats": null,
    "channelDailySeries": null,
    "metricDailyBreakdown": null,
    "contactsByCountry": null,
    "ai_human_split": null
  }
}
```

**Alan notları:**

- `heatmap.buckets[].weekday` — `0` Pazar gününden `6` Cumartesi gününe kadardır.
- `numberStats`, `channelDailySeries`, `metricDailyBreakdown`, `contactsByCountry`, `ai_human_split` — her biri, raporlama veritabanı hesabınız için kullanılamadığında bağımsız olarak `null` değerini alır; diğer tüm bloklar yine de döner.

---

## Yapay Zeka gösterge paneli içgörüleri

Bir tarih aralığında hesabın mesajlaşması hakkında yapay zeka tarafından yazılmış üç kısa içgörü döndürür: bir başarı, izlenmesi gereken bir şey ve bir ipucu — yorumlamanız gereken sayılar yerine doğrudan bir rapora yapıştırabileceğiniz cümleler. Yalnızca hesabın kendi mesaj metriklerinden oluşturulmuştur.

`GET /analytics/dashboard-ai-insights`

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `startDate` | Evet | Aralık başlangıcı, `YYYY-MM-DD`. |
| `endDate` | Evet | Aralık bitişi, `YYYY-MM-DD`. |

Bu uç nokta hesap genelindedir; kampanya veya temsilci kapsamı almaz.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ startDate: "2026-05-01", endDate: "2026-05-31" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/dashboard-ai-insights",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"startDate": "2026-05-01", "endDate": "2026-05-31"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "data": {
    "insights": [
      { "tone": "win", "title": "Reply rate is up", "detail": "Your reply rate climbed to 43% this period, up from 36% the period before." },
      { "tone": "watch", "title": "Bookings slowed midweek", "detail": "Wednesday bookings dropped to a third of Monday's, worth a look at your Wednesday follow-up timing." },
      { "tone": "tip", "title": "Re-send to non-repliers", "detail": "212 contacts received a message but never replied — a short follow-up template often recovers 10-15% of them." }
    ]
  }
}
```

`startDate` veya `endDate` eksik olduğunda `400` döner.

---

## Varlık etkinlik zaman çizelgesi

Tek bir kişiye, anlaşmaya veya göreve ait etkinlikleri, en yeniden başlayarak tek bir zaman çizelgesi olarak döndürür: mesajlar, randevular, notlar ve durum değişiklikleri genelinde neyin, ne zaman gerçekleştiği. Bunu, birden fazla liste uç noktasını birleştirmek zorunda kalmadan "bu kişiyle neler oldu" sorusunu yanıtlamak için kullanın.

`GET /analytics/entity-activity`

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `entityType` | Evet | `contact`, `deal` veya `task`. |
| `entityId` | Evet | Zaman çizelgesi döndürülecek kaydın kimliği. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/entity-activity?entityType=contact&entityId=contact456&apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ entityType: "contact", entityId: "contact456" });
const res = await fetch(`https://api.youraiconnector.com/v1/analytics/entity-activity?${params}`, {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/analytics/entity-activity",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"entityType": "contact", "entityId": "contact456"},
)
data = res.json()
```

**Yanıt**

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "evt_9",
        "kind": "appointment_booked",
        "at": "2026-05-31T14:02:11.000Z",
        "label": "Booked an appointment for June 3",
        "detail": "Consultation call, 30 minutes"
      },
      {
        "id": "evt_8",
        "kind": "message_replied",
        "at": "2026-05-31T13:58:02.000Z",
        "label": "Replied: \"Yes, that time works\""
      }
    ]
  }
}
```

Eksik veya geçersiz bir `entityType`/`entityId`, `400` döndürür. Hesabınızda bulunmayan bir varlık `404` döndürür, böylece diğer hesapların kimlikleri tahmin edilemez kalır.

---

## Toplu etkinlik sayıları (eski)

[Mesaj hacmi özeti](#message-volume-summary) ile aynı toplu etkinlik sayılarını döndürür, ancak bazı eski entegrasyonların üzerine inşa edildiği camelCase biçiminde (`contact_created` yerine `contactCreated`, `by_date` yerine `byDate`). Yeni entegrasyonlar için `/analytics/summary` tercih edin; bu uç nokta yalnızca uygulama içi kontrol paneli ile API'nin tek bir uygulamayı paylaşması için mevcuttur.

`GET /analytics/aggregate`

| Parametre | Gerekli | Açıklama |
|---|---|---|
| `startDate` | Hayır | Aralık başlangıcı, ISO tarih veya tarih-saat. `/analytics/summary` ile aynı pencereyi varsayılan olarak kullanır. |
| `endDate` | Hayır | Aralık sonu, ISO tarih veya tarih-saat. |
| `campaignId` | Hayır | Yalnızca bu kampanyaya ait etkinlikleri sayın (`campaign_id` de kabul edilir). Eski; `agent_id` tercih edin. |
| `agent_id` | Hayır | Yalnızca bu Yapay Zeka Temsilcisine ait etkinlikleri sayın (`agentId` de kabul edilir). |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/analytics/aggregate?startDate=2026-05-01&endDate=2026-05-31&apiKey=YOUR_API_KEY"
```

**Yanıt**

```json
{
  "success": true,
  "data": {
    "from": "2026-05-01",
    "to": "2026-05-31",
    "total": 1240,
    "byAnalyticType": {
      "total": 1240,
      "sent": 800,
      "delivered": 760,
      "read": 540,
      "replied": 210,
      "booked": 35,
      "contactCreated": 120,
      "creditsSpent": 412.5,
      "creditsRecharged": 500
    },
    "byDate": [
      { "date": "2026-05-01", "byAnalyticType": { "total": 40, "sent": 25, "delivered": 24, "read": 18, "replied": 7, "booked": 1, "contactCreated": 4, "creditsSpent": 13.5, "creditsRecharged": 0 } }
    ]
  }
}
```

---

## Ajans alt hesap toplamı


---

## Analytics API hataları

Analytics uç noktaları standart hata zarfını döndürür:

```json
{
  "success": false,
  "error": "Date range too large. Maximum is 366 days."
}
```

Bir analiz uç noktasında, geçersiz bir tarih biçimi veya aralık dışı bir pencere `400` döndürür ve bilinmeyen bir `campaign_id` veya `agent_id`, `404` döndürür. Her ikisini de kabul eden bir uç noktaya hem `campaign_id` hem de `agent_id` göndermek de bir `400`'dır — en fazla birini gönderin. Yalnızca PG raporlama uç noktaları (Metrik serileri, Görüşme sonuçları, Ajans toplamı), raporlama veritabanı hesabınız için yanıt veremediğinde sıfırlarla dolu bir `200` yerine `"error_code": "analytics_unavailable"` ile `503` döndürür — kısa süre sonra tekrar deneyin. Her uç noktanın döndürebileceği paylaşılan kodlar — `401`, `403` (planınız API erişimini içermiyor veya ajans toplamında hesabınız Ajans/Geliştirici değil), `429` (hız sınırı) ve `500` — [Hatalar ve Sayfalama](errors-and-pagination.md) bölümünde yeniden deneme rehberliği ile listelenmiştir.

---

## Sonraki adımlar

- [Kimlik Doğrulama](authentication.md) — bir isteğin kimliğini doğrulamak için kullanılan dört yöntem.
- [Hatalar ve Hız Sınırları](errors-and-pagination.md) — durum kodları ve dakikada 300 istek sınırı.
- [Kampanyalar API](campaigns.md) — bu rakamların filtrelenebileceği kampanyalar.