Analytics & Reports API

Diese schreibgeschützten Endpunkte ermöglichen es Ihnen, die Aktivitäten Ihres Kontos in Ihre eigenen Dashboards und Berichte zu importieren: Nachrichten-Ereigniszahlen, Kreditverbrauch, KI-Ausgaben sowie dieselben Diagramme und Erkenntnisse, die das In-App-Dashboard anzeigt. Dieser Leitfaden behandelt:

Zusammenfassung — Zähler für das Nachrichtenvolumen (gesendet, zugestellt, gelesen, beantwortet, gebucht, erstellte Kontakte, Credits).
Credits — ein detailliertes, paginiertes Protokoll der Kreditnutzung mit Summen und Aufschlüsselungen.
KI-Kosten — eine tägliche Zusammenfassung der KI-Ausgaben.
Metrik-Reihen — eine für Diagramme geeignete Zeitreihe für eine oder mehrere Metriken, gruppiert nach Kampagne, Kanal, KI-Agent oder Nummer.
Konversationsergebnisse — wie Konversationen endeten, basierend auf dem von der KI zugewiesenen Ergebnis-Tag.
Dashboard-Erkenntnisse und Dashboard-KI-Erkenntnisse — die vollständigen Daten hinter dem In-App-Dashboard, einschließlich der von der KI verfassten Zusammenfassungen.
Entitätsaktivität — die Zeitleiste eines einzelnen Kontakts, Deals oder einer Aufgabe.
Aggregierte Ereigniszahlen — eine ältere, in camelCase gehaltene Form der Zusammenfassung, die für bestehende Integrationen beibehalten wurde.

Jeder Endpunkt auf dieser Seite erfordert einen exakten Gültigkeitsbereich, nicht beide: Übergeben Sie maximal einen von campaign_id (veraltet) oder agent_id, sofern der Endpunkt dies akzeptiert. Das Senden beider führt zu 400, und eine ID, die nicht zu Ihrem Konto gehört, gibt 404 statt 403 zurück, sodass die IDs anderer Konten nicht erraten werden können.

Alle unten aufgeführten Pfade sind relativ zur API-Basis-URL:

https://api.youraiconnector.com/v1

Jede Anfrage muss authentifiziert sein. Siehe Authentifizierung für die vier akzeptierten Methoden. Die Beispiele hier verwenden den X-API-Key-Header (und eine Abfrageparameter-Form für cURL).

Datumsbereich

Alle drei Endpunkte akzeptieren dieselben optionalen Datumsfilter:

Parameter	Beschreibung
`from`	Beginn des Bereichs, `YYYY-MM-DD`, inklusive. Standardmäßig vor 30 Tagen.
`to`	Ende des Bereichs, `YYYY-MM-DD`, inklusive. Standardmäßig heute.

Daten werden in UTC interpretiert. Der Bereich ist standardmäßig auf die letzten 30 Tage eingestellt und auf 366 Tage begrenzt — ein größerer Bereich gibt 400 zurück. from darf nicht nach to liegen.

Das `truncated`-Flag

Die Endpunkte Zusammenfassung und Kredite begrenzen die Anzahl der Datensätze, die eine einzelne Anfrage scannt. Wenn Ihr Bereich so umfangreich ist, dass dieses Limit erreicht wird, enthält die Antwort "truncated": true. Wenn Sie dies sehen, basieren die Zahlen auf einem teilweisen Scan — schränken Sie Ihren Datumsbereich ein (oder blättern Sie mit einem kleineren Fenster), um vollständige Zahlen zu erhalten.

Hinweis: Kosten- und Token-Angaben sind nur für KI-Aufrufe enthalten, die über Ihre eigenen Anbieter-API-Schlüssel abgerechnet werden. Wenn Kostenangaben für Ihr Konto ausgeblendet sind, setzt die Antwort "costs_redacted": true und die Kostenfelder werden als null zurückgegeben.

Zusammenfassung des Nachrichtenvolumens

Gibt aggregierte Zähler für Nachrichtenereignisse für Ihr Konto zurück, sowohl als Bereichssummen als auch als tägliche Reihe. Jeder Tag im Bereich erscheint in by_date — ruhige Tage werden mit Null aufgefüllt. Filtern Sie optional auf eine einzelne Kampagne mit campaign_id.

GET /analytics/summary

Parameter	Erforderlich	Beschreibung
`from`	Nein	Bereichsbeginn, `YYYY-MM-DD`.
`to`	Nein	Bereichsende, `YYYY-MM-DD`.
`campaign_id`	Nein	Nur Ereignisse zählen, die zu dieser Kampagne gehören.

cURL

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

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

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()

Antwort

{
  "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
}

Jeder Eintrag in by_date verfügt über dieselben Zählerfelder wie totals, zuzüglich eines date.

Wenn Sie eine campaign_id übergeben, die nicht zu Ihrem Konto gehört, lautet die Antwort 404 mit { "success": false, "error": "Campaign not found" }.

Kreditverbrauch

Gibt den Kreditverbrauch über den Bereich zurück: eine paginierte Liste einzelner Datensätze sowie Bereichssummen und Aufschlüsselungen nach Grund und Kampagne.

GET /analytics/credits

Parameter	Erforderlich	Beschreibung
`from`	Nein	Bereichsbeginn, `YYYY-MM-DD`.
`to`	Nein	Bereichsende, `YYYY-MM-DD`.
`campaign_id`	Nein	Nur Nutzung einbeziehen, die dieser Kampagne zugerechnet wird.
`limit`	Nein	Seitengröße für `records`, 1–100. Standardwert ist 50.
`cursor`	Nein	Übergeben Sie den `next_cursor` der vorherigen Seite, um die nächste Seite abzurufen.

Anpassungen vs. Verbrauch: Saldoänderungen wie Boni, Planverlängerungen und Korrekturen sind von totals und den Aufschlüsselungen ausgeschlossen – sie stellen keinen tatsächlichen Verbrauch dar. Sie erscheinen weiterhin in der records-Liste, markiert mit "is_adjustment": true.

Summen und Aufschlüsselungen erscheinen nur auf der ersten Seite (wenn kein cursor angegeben ist). Auf späteren Seiten werden totals, by_reason, by_reason_cost und by_campaign als null zurückgegeben – nur das records-Array wird fortgesetzt. Dies vermeidet ein erneutes Scannen des gesamten Bereichs für jede Seite.

cURL

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

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

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.

Antwort (erste Seite)

{
  "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
}

Feldhinweise:

amount — für den Datensatz berechnete Kredite. Null für Datensätze, die über Ihren eigenen Provider-API-Schlüssel abgerechnet werden.
is_adjustment — true für Saldoänderungen (von Summen/Aufschlüsselungen ausgeschlossen).
cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — nur ausgefüllt bei Datensätzen, die über Ihren eigenen Provider-API-Schlüssel abgerechnet werden; ansonsten null oder null.
is_test — true für Playground-/Testläufe, die niemals in Rechnung gestellt werden.
next_cursor — der Cursor für die nächste Seite oder null, wenn keine weiteren Datensätze vorhanden sind.

KI-Kosten-Rollup

Gibt das tägliche KI-Ausgaben-Rollup für Ihr Konto zurück. Dies liest voraggregierte Tagessummen, ist also auch über lange Zeiträume hinweg schnell. Jeder Tag im Bereich erscheint in days – ruhige Tage werden mit Null aufgefüllt.

GET /analytics/ai-cost

Parameter	Erforderlich	Beschreibung
`from`	Nein	Start des Bereichs, `YYYY-MM-DD`.
`to`	Nein	Ende des Bereichs, `YYYY-MM-DD`.

cURL

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

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

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()

Antwort

{
  "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
}

Feldhinweise:

byok_usd — Ausgaben, die über Ihre eigenen API-Schlüssel des Anbieters abgerechnet werden.
platform_usd — Der Teil der Ausgaben, der über die Plattform und nicht über Ihren eigenen Schlüssel abgewickelt wurde.
input_usd, output_usd, cache_creation_usd, cache_read_usd — Die Kostenkomponenten, aus denen sich total_usd zusammensetzt.
by_provider — Ausgaben in USD, sortiert nach dem Namen des KI-Anbieters.
USD-Beträge werden nur für Konten zurückgegeben, die ihren eigenen Anbieterschlüssel verwenden. Bei Konten, die mit Guthaben bezahlen, sind alle USD-Felder null und costs_redacted ist true (die Anzahl der Aufrufe bleibt sichtbar).

Metrik-Reihen

Gibt eine oder mehrere Metrik-Zeitreihen in einem Aufruf zurück, optional gruppiert nach bis zu zwei Dimensionen – der Endpunkt zur Anbindung eines Diagramms. Eine einzelne Anfrage kann “gesendet und beantwortet pro Tag, pro Kanal, für diese Kampagne” beantworten, ohne dass ein Aufruf pro Kampagne erforderlich ist.

GET /analytics/series

Jede Antwort enthält ein labels-Array (die Zeitachse, über den gesamten Bereich mit Nullen gefüllt) und einen Eintrag in series pro Gruppe, wobei jeder ein Array pro angeforderter Metrik enthält, das auf labels ausgerichtet ist. Reihen nach limit werden nicht verworfen – sie werden in other_bucket zusammengefasst, berechnet als Bereichssumme abzüglich der zurückgegebenen Reihen, sodass ein gerendertes Diagramm immer Ihre tatsächlichen Zahlen ergibt; truncated ist true, wann immer dies geschieht.

Woher die Zahlen stammen: sent, delivered, read und replied stammen aus Nachrichtendatensätzen, die den Kanal und die sendende Nummer enthalten. booked, contact_created und credits_spent stammen aus dem Ereignisstrom, der keine sendende Nummer enthält, daher landen diese Metriken im null-Nummern-Bucket, wenn Sie nach number gruppieren.

Parameter	Erforderlich	Beschreibung
`from`	Nein	Bereichsbeginn, `YYYY-MM-DD`. Standardmäßig vor 30 Tagen.
`to`	Nein	Bereichsende, `YYYY-MM-DD`. Standardmäßig heute.
`metrics`	Nein	Durch Kommas getrennte Liste aus `sent`, `ai_sent`, `human_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`. Standardmäßig `sent,replied`. Eine unbekannte Metrik gibt `400` zurück.
`group_by`	Nein	Durch Kommas getrennte Liste von bis zu zwei Dimensionen aus `date`, `campaign`, `channel`, `agent`, `number`. `date` wird akzeptiert, hat aber keine Auswirkung – jede Antwort enthält bereits die Zeitachse. Für eine einzelne kontoweite Reihe weglassen.
`granularity`	Nein	`day` (Standard), `week` oder `month`. Wochen-Buckets beginnen am Montag, Monats-Buckets am 1.
`limit`	Nein	Wie viele Reihen zurückgegeben werden sollen, bevor der Rest in `other_bucket` zusammengefasst wird, 1–50. Standardmäßig 12.
`campaign_id`	Nein	Nur Aktivitäten zählen, die zu dieser Kampagne gehören. Veraltet; bevorzugen Sie `agent_id`.
`agent_id`	Nein	Nur Aktivitäten zählen, die zu diesem KI-Agenten gehören.
`channel`	Nein	Nur Aktivitäten auf diesem Kanal zählen, zum Beispiel `whatsapp`.

Der Datumsbereich dieses Endpunkts ist auf 92 Tage begrenzt (enger als die 366-Tage-Begrenzung, die an anderer Stelle auf dieser Seite verwendet wird).

cURL

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

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

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()

Antwort

{
  "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
}

Feldhinweise:

key — die Identität einer Reihe. Nur die Schlüssel für die angeforderten group_by-Dimensionen sind vorhanden; eine Dimension, deren Wert für eine Zeile unbekannt ist (eine Nachricht ohne Kampagne, ein Ereignis ohne Kanal), wird als null zurückgegeben, anstatt verworfen zu werden, sodass die Reihen immer noch die Summen ergeben.
other_bucket — null, wenn nichts zusammengefasst wurde.
Dieser Endpunkt gibt 503 mit "error_code": "analytics_unavailable" zurück, wenn die Berichtsdatenbank für Ihr Konto nicht antworten kann, anstatt ein 200 voller Nullen – ein auf Null gesetztes Diagramm würde als Tatsache gelesen werden.

Konversationsergebnisse

Gibt zurück, wie Konversationen über einen Datumsbereich endeten: eine tägliche Anzahl für jedes von der KI zugewiesene Ergebnis-Tag sowie Bereichssummen für Antworten, Buchungen, Übergaben an einen Menschen und Konversationen, die die KI nie klassifiziert hat.

GET /analytics/outcomes

Übergeben Sie group_by=tag, um die Zeitachse zusammenzufassen und nur Bereichssummen pro Tag zu erhalten – in diesem Modus ist labels leer und das counts-Array jedes Tags ist leer, während total weiterhin gefüllt ist.

Parameter	Erforderlich	Beschreibung
`from`	Nein	Bereichsbeginn, `YYYY-MM-DD`. Standardmäßig vor 30 Tagen.
`to`	Nein	Bereichsende, `YYYY-MM-DD`. Standardmäßig heute.
`campaign_id`	Nein	Zählt nur Konversationen mit Kontakten, die sich aktuell in dieser Kampagne befinden. Veraltet; bevorzugen Sie `agent_id`.
`agent_id`	Nein	Zählt nur Ergebnisse, die zu diesem KI-Agenten gehören.
`group_by`	Nein	`date` (Standard) behält die täglichen Zählungen bei; `tag` fasst diese zu Bereichssummen zusammen.

Der Datumsbereich dieses Endpunkts ist auf 92 Tage begrenzt.

cURL

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

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

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()

Antwort

{
  "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
  }
}

Feldhinweise:

by_tag[].tag — null für Konversationen, denen die KI kein Ergebnis-Tag zugewiesen hat.
totals.human_alerted — Konversationen, die an einen Menschen übergeben wurden; dies wird bei jeder Übergabe protokolliert und wurde bisher von keinem Endpunkt bereitgestellt.
Gleiches 503/analytics_unavailable-Verhalten wie bei der Metrik-Serie, wenn die Reporting-Datenbank keine Antwort geben kann.

Dashboard-Einblicke

Gibt die vollständige Dashboard-Nutzlast für einen Datumsbereich in einem Aufruf zurück: eine Heatmap der Antwortrate nach Wochentag und Uhrzeit, die Kampagnen-Bestenliste, das Volumen pro Kanal, exakte Summen pro Verbindung, tägliche Metrik-Aufschlüsselungen (kontoweit, pro Kanal und pro Nummer), Herkunft der Kontakte, Antwortzeit im Posteingang und einen Feed mit kürzlichen Aktivitäten. Dies ist die umfangreichste Reporting-Nutzlast der API — sie treibt das In-App-Dashboard direkt an.

GET /analytics/dashboard-insights

Parameter	Erforderlich	Beschreibung
`startDate`	Ja	Bereichsbeginn, `YYYY-MM-DD`.
`endDate`	Ja	Bereichsende, `YYYY-MM-DD`.
`campaignId`	Nein	Berücksichtigt nur Aktivitäten, die zu dieser Kampagne gehören (`campaign_id` ebenfalls akzeptiert). Veraltet; bevorzugen Sie `agent_id`.
`agent_id`	Nein	Berücksichtigt nur Aktivitäten, die zu diesem KI-Agenten gehören (`agentId` ebenfalls akzeptiert). Innerhalb eines Agenten-Bereichs wird die Kampagnen-Bestenliste nur aus den Aktivitäten dieses Agenten erstellt.

Dieser Endpunkt verwendet startDate/endDate (nicht from/to), da er seine Implementierung mit dem In-App-Dashboard teilt. Der Bereich ist auf 92 Tage begrenzt und wird gekürzt, nicht abgelehnt, wenn er breiter ist.

Null bedeutet nicht verfügbar, nicht null. Mehrere Blöcke (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) werden aus der Reporting-Datenbank berechnet und geben null zurück, wenn diese für Ihr Konto keine Antwort liefern kann. Rendern Sie einen null-Block nicht als leeres Diagramm.

cURL

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

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

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()

Antwort (gekürzt — diese Nutzlast ist groß; siehe die API-Referenz für das vollständige Schema)

{
  "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
  }
}

Feldhinweise:

heatmap.buckets[].weekday — 0 ist Sonntag bis 6 ist Samstag.
numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — jeder ist unabhängig null, wenn die Reporting-Datenbank für Ihr Konto nicht verfügbar ist; alle anderen Blöcke werden weiterhin zurückgegeben.

KI-Dashboard-Einblicke

Gibt drei kurze, von der KI verfasste Einblicke über die Nachrichtenübermittlung des Kontos über einen Datumsbereich zurück: ein Erfolg, ein Punkt zur Beobachtung und ein Tipp — Sätze, die Sie direkt in einen Bericht kopieren können, anstatt Zahlen, die Sie noch interpretieren müssen. Ausschließlich aus den eigenen Nachrichtenmetriken des Kontos generiert.

GET /analytics/dashboard-ai-insights

Parameter	Erforderlich	Beschreibung
`startDate`	Ja	Bereichsbeginn, `YYYY-MM-DD`.
`endDate`	Ja	Bereichsende, `YYYY-MM-DD`.

Dieser Endpunkt ist kontoübergreifend – er erfordert keinen Kampagnen- oder Agenten-Geltungsbereich.

cURL

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

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

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()

Antwort

{
  "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." }
    ]
  }
}

Fehlende startDate oder endDate führen zu 400.

Zeitstrahl der Entitätsaktivitäten

Gibt die Aktivitäten eines einzelnen Kontakts, Deals oder einer Aufgabe als einen Zeitstrahl zurück, beginnend mit dem Neuesten: Was ist wann passiert, über Nachrichten, Termine, Notizen und Statusänderungen hinweg. Verwenden Sie dies, um die Frage „Was ist mit dieser Person passiert?“ zu beantworten, ohne mehrere Listen-Endpunkte zusammenführen zu müssen.

GET /analytics/entity-activity

Parameter	Erforderlich	Beschreibung
`entityType`	Ja	`contact`, `deal` oder `task`.
`entityId`	Ja	ID des Datensatzes, dessen Zeitstrahl zurückgegeben werden soll.

cURL

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

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

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()

Antwort

{
  "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\""
      }
    ]
  }
}

Ein fehlendes oder ungültiges entityType/entityId führt zu 400. Eine Entität, die in Ihrem Konto nicht existiert, führt zu 404, sodass die IDs anderer Konten nicht erraten werden können.

Aggregierte Ereignisanzahlen (Legacy)

Gibt dieselben aggregierten Ereignisanzahlen zurück wie die Zusammenfassung des Nachrichtenvolumens, jedoch im camelCase-Format (contactCreated statt contact_created, byDate statt by_date), für das einige ältere Integrationen entwickelt wurden. Bevorzugen Sie /analytics/summary für neue Integrationen – dieser Endpunkt existiert nur, damit das In-App-Dashboard und die API dieselbe Implementierung nutzen.

GET /analytics/aggregate

Parameter	Erforderlich	Beschreibung
`startDate`	Nein	Bereichsbeginn, ISO-Datum oder Datum-Uhrzeit. Standardmäßig dasselbe Fenster, das `/analytics/summary` verwendet.
`endDate`	Nein	Bereichsende, ISO-Datum oder Datum-Uhrzeit.
`campaignId`	Nein	Zählt nur Ereignisse, die zu dieser Kampagne gehören (`campaign_id` ebenfalls akzeptiert). Legacy; bevorzugen Sie `agent_id`.
`agent_id`	Nein	Zählt nur Ereignisse, die zu diesem KI-Agenten gehören (`agentId` ebenfalls akzeptiert).

cURL

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

Antwort

{
  "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 } }
    ]
  }
}

Rollup für Agentur-Unterkonten

Analytics-API-Fehler

Analytics-Endpunkte geben das Standard-Fehler-Envelope zurück:

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

An einem Analyse-Endpunkt führen ein ungültiges Datumsformat oder ein Fenster außerhalb des zulässigen Bereichs zu 400, und ein unbekanntes campaign_id oder agent_id führt zu 404. Das Senden von sowohl campaign_id als auch agent_id an einen Endpunkt, der eines von beiden akzeptiert, ist ebenfalls ein 400 – übergeben Sie maximal eines. Die reinen PG-Reporting-Endpunkte (Metrik-Serien, Konversationsergebnisse, Agentur-Rollup) geben 503 mit "error_code": "analytics_unavailable" zurück, anstatt ein 200 voller Nullen, wenn die Reporting-Datenbank für Ihr Konto keine Antwort geben kann – versuchen Sie es in Kürze erneut. Die gemeinsamen Codes, die jeder Endpunkt zurückgeben kann – 401, 403 (Ihr Plan beinhaltet keinen API-Zugriff oder bei einem Agentur-Rollup ist Ihr Konto kein Agentur-/Entwickler-Konto), 429 (Ratenbegrenzung) und 500 – sind mit Hinweisen zum erneuten Versuch unter Fehler & Paginierung aufgeführt.

Nächste Schritte

Authentifizierung — die vier Möglichkeiten zur Authentifizierung einer Anfrage.
Fehler & Ratenbegrenzungen — Statuscodes und das Limit von 300 Anfragen/Min.
Kampagnen-API — die Kampagnen, nach denen diese Zahlen gefiltert werden können.

Analytics & Reports API #

Datumsbereich #

Das truncated-Flag #

Zusammenfassung des Nachrichtenvolumens #

Kreditverbrauch #

KI-Kosten-Rollup #

Metrik-Reihen #

Konversationsergebnisse #

Dashboard-Einblicke #

KI-Dashboard-Einblicke #

Zeitstrahl der Entitätsaktivitäten #

Aggregierte Ereignisanzahlen (Legacy) #

Rollup für Agentur-Unterkonten #

Analytics-API-Fehler #

Nächste Schritte #

Analytics & Reports API

Datumsbereich

Das `truncated`-Flag

Zusammenfassung des Nachrichtenvolumens

Kreditverbrauch

KI-Kosten-Rollup

Metrik-Reihen

Konversationsergebnisse

Dashboard-Einblicke

KI-Dashboard-Einblicke

Zeitstrahl der Entitätsaktivitäten

Aggregierte Ereignisanzahlen (Legacy)

Rollup für Agentur-Unterkonten

Analytics-API-Fehler

Nächste Schritte