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 — Nachrichtenvolumen-Zähler (gesendet, zugestellt, gelesen, beantwortet, gebucht, erstellte Kontakte, Credits).
Credits — ein detailliertes, paginiertes Protokoll der Credit-Nutzung 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 — Konversationen im Zeitverlauf, gruppiert nach den Kontakt-Tags, die sie tragen (die Abschluss-Tags, die Ihr Agent anwendet).
Konversationskosten: die durchschnittlichen Credit-Kosten einer Konversation, die die KI allein abgewickelt hat, im Vergleich zu einer, in die Ihr Team eingegriffen hat.
Dashboard-Einblicke und Dashboard-KI-Einblicke — die vollständigen Daten hinter dem In-App-Dashboard, einschließlich der von der KI geschriebenen Zusammenfassungen.
Entitätsaktivität — die Zeitleiste eines einzelnen Kontakts, Deals oder einer Aufgabe.
Aggregierte Ereignisanzahl — 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.

Nur zwei Endpunkte filtern nach Kontakt-Tag. tag_ids (mit tag_match) wird von Dashboard-Einblicken und Aggregierten Ereignisanzahlen berücksichtigt – das sind die beiden, die der Alle Tags-Filter des In-App-Dashboards verwendet. Zusammenfassung, Metrikreihen und Konversationsergebnisse validieren den Parameter (eine fehlerhafte ID-Liste gibt immer noch 400 zurück), wenden ihn aber nicht an: Sie erhalten kontoweite Zahlen zurück, ohne dass ein Fehler darauf hinweist. Lesen Sie eine ungefilterte Summe nicht als tag-gefilterte Summe.

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.

Guthabenstand

GET /users/me/credits — der aktuelle Guthabenstand Ihres Kontos auf einen Blick: wie viel noch ausgegeben werden kann, das monatliche Kontingent sowie die Einstellungen für automatische Aufladung und niedriges Guthaben. Die oben genannte Guthabennutzung ist eine Historie; dies ist der aktuelle Kontostand. Teammitglieder, die diesen abrufen, benötigen Zugriff auf die Abrechnung; der Schlüssel des Kontoinhabers verfügt immer darüber.

curl "https://api.youraiconnector.com/v1/users/me/credits?apiKey=YOUR_API_KEY"

const res = await fetch("https://api.youraiconnector.com/v1/users/me/credits", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { balance } = await res.json();

Antwort (200)

{
  "success": true,
  "balance": 1837.5,
  "monthly_credits": 2000,
  "used_this_month": null,
  "auto_recharge_enabled": true,
  "low_credit_threshold": null
}

Feld	Bedeutung
`balance`	Noch verfügbares Guthaben — dieselbe Zahl, die auf der Guthabenkarte angezeigt wird.
`monthly_credits`	Das monatliche Kontingent des Plans oder `null`, wenn das Konto keines hat.
`used_this_month`	In diesem Monat für ein Zuweisungskonto (Agentur-Unterkonto) verbrauchtes Guthaben; `null` für ein reguläres Konto — verwenden Sie dafür die Guthabennutzung.
`auto_recharge_enabled`	Ob die automatische Aufladung aktiviert ist.
`low_credit_threshold`	Der Kontostand, bei dem der Webhook für niedriges Guthaben ausgelöst wird, oder `null`, wenn der Standardwert gilt.

Agenturen können sub_account_id übergeben, um den Kontostand eines Kundenkontos auszulesen. Innerhalb einer Automatisierung gibt der Schritt Guthaben prüfen dieselben Felder zurück.

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.

conversations zählt die Konversationen (Chat-Sitzungen), die in jedem Bucket begonnen haben, und conversation_credits, was diese Konversationen gekostet haben, berechnet genau wie unter Konversationskosten. Teilen Sie den einen Wert durch den anderen pro Bucket, um die durchschnittlichen Kosten pro Konversation im Zeitverlauf zu erhalten. Wenn Sie nach Kampagne, Agent, Kanal oder Nummer gruppieren oder filtern, wird eine Konversation derjenigen zugeordnet, zu der ihre erste Nachricht gehört.

Parameter	Erforderlich	Beschreibung
`from`	Nein	Start des Bereichs, `YYYY-MM-DD`. Standardmäßig vor 30 Tagen.
`to`	Nein	Ende des Bereichs, `YYYY-MM-DD`. Standardmäßig heute.
`metrics`	Nein	Durch Kommas getrennte Liste von `sent`, `ai_sent`, `human_sent`, `automated_sent`, `delivered`, `read`, `replied`, `booked`, `contact_created`, `credits_spent`, `conversations`, `conversation_credits`. 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. Weglassen für eine einzelne kontoweite Reihe.
`granularity`	Nein	`day` (Standard), `week` oder `month`. Wochen-Buckets beginnen am Montag, Monats-Buckets am Ersten.
`limit`	Nein	Anzahl der zurückzugebenden Reihen, bevor der Rest in `other_bucket` zusammengefasst wird, 1–50. Standardmäßig 12.
`campaign_id`	Nein	Zählt nur Aktivitäten, die zu dieser Kampagne gehören. Veraltet; bevorzugen Sie `agent_id`.
`agent_id`	Nein	Zählt nur Aktivitäten, die zu diesem KI-Agenten gehören.
`channel`	Nein	Zählt nur Aktivitäten auf diesem Kanal, 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 Konversationsergebnisse über einen Datumsbereich zurück: eine tägliche Anzahl von Konversationen unter jedem Kontakt-Tag sowie Bereichssummen für Antworten, Buchungen, Übergaben an einen Menschen und Konversationen, deren Kontakt kein Tag trägt.

Das Tag ist ein Kontakt-Tag: die Tags, die Ihr KI-Agent mit seinem Tag-Tool, automatischen Tag-Regeln, der API oder Ihrem Team anwendet. Es handelt sich nicht um eine Bezeichnung pro Konversation. Eine Konversation wird unter den Tags gezählt, die ihr Kontakt zum Zeitpunkt der Anfrage trägt. Ein Kontakt mit mehreren Tags zählt also einmal unter jedem Tag, und ein später entferntes Tag fällt auch aus vergangenen Tagen heraus. Geben Sie Ihrem Agenten ein Abschluss-Tag pro Ergebnis (zum Beispiel resolved_ai, handoff_asked_for_human) und dieser Endpunkt gibt die Einbeziehung und Übergabegründe im Zeitverlauf zurück.

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_id": "tag_8f2k1", "tag": "interested", "total": 84, "counts": [3, 5] },
    { "tag_id": "tag_c91xq", "tag": "not_interested", "total": 40, "counts": [1, 2] },
    { "tag_id": null, "tag": null, "total": 12, "counts": [0, 1] }
  ],
  "totals": {
    "sessions": 260,
    "replied": 210,
    "booked": 35,
    "human_alerted": 18,
    "unresolved": 12
  }
}

Feldhinweise:

by_tag[].tag / by_tag[].tag_id — der Name und die ID des Kontakt-Tags; beides null in der Zeile der Konversationen, deren Kontakt kein Tag trägt. Es werden maximal 20 Tags zurückgegeben, beginnend mit dem höchsten Volumen.
totals.sessions — eindeutige Konversationen, die im Zeitraum gestartet wurden. Dies ist nicht die Summe von by_tag[].total: ein Kontakt mit drei Tags trägt eine Konversation zu drei Zeilen bei.
totals.unresolved — Konversationen, deren Kontakt kein Tag trägt.
totals.human_alerted — Konversationen, die an einen Menschen übergeben wurden; dies wird bei jeder Übergabe vermerkt und wurde bisher von keinem Endpunkt bereitgestellt.
Gleiche 503/analytics_unavailable-Haltung wie bei Metrik-Reihen, wenn die Berichtsdatenbank nicht antworten kann.

Konversationskosten

Gibt die durchschnittlichen Kosten einer Konversation über einen Datumsbereich zurück, aufgeschlüsselt nach deren Verlauf. Dies ist die Zahl, die Sie einem Kunden als Return on Investment zeigen können: Was eine Konversation kostet, die die KI allein abgewickelt hat, im Vergleich zu einer, bei der Ihr Team eingreifen musste.

GET /analytics/conversation-costs

Parameter	Erforderlich	Beschreibung
`from`	Nein	Startdatum, `YYYY-MM-DD`, inklusive. Standardmäßig vor 30 Tagen.
`to`	Nein	Enddatum, `YYYY-MM-DD`, inklusive. Standardmäßig heute. Maximaler Bereich 31 Tage.
`sub_account_id`	Nein	Agentur-Schlüssel: Berichten Sie über dieses Kundenkonto anstelle Ihres eigenen.

curl "https://api.youraiconnector.com/v1/analytics/conversation-costs?from=2026-08-26&to=2026-09-24&apiKey=YOUR_API_KEY"

Antwort

{
  "success": true,
  "from": "2026-08-26",
  "to": "2026-09-24",
  "sessions": 564,
  "total_credits": 5957,
  "summary": {
    "contained": { "sessions": 503, "credits": 5168, "avg_credits": 10.2744 },
    "handed_off": { "sessions": 50, "credits": 781, "avg_credits": 15.62 },
    "no_ai": { "sessions": 11, "credits": 8, "avg_credits": 0.7273 }
  },
  "sessions_truncated": false
}

Feldhinweise:

Zählt Konversationen (Chat-Sitzungen), die im Bereich begonnen haben, wobei die innerhalb des Fensters jeder Konversation berechneten Credits abzüglich Rückerstattungen berücksichtigt werden. Credits, die außerhalb einer Konversation ausgegeben wurden (tägliche Zusammenfassungen, monatliche Gebühren, Automatisierungen, die nicht von einem Kontakt gestartet wurden, wie Webhook- oder RSS-Trigger), sind nicht Teil davon. Automatisierungsläufe und KI-Schritte, die von einem Kontakt gestartet wurden, zählen seit dem 26. September 2026 zur Konversation dieses Kontakts.
contained: Die KI hat geantwortet und niemand aus Ihrem Team musste eingreifen. handed_off: Jemand hat eine Nachricht gesendet, nachdem die KI geantwortet hatte, oder die KI hat einen Menschen alarmiert. no_ai: Die KI hat nie geantwortet (zum Beispiel Chats, die Ihr Team bei pausierter KI bearbeitet).
Es werden maximal 20.000 Konversationen gezählt; sessions_truncated ist true, wenn der Bereich mehr enthielt, also schränken Sie ihn ein.
Erfordert die Abrechnungsberechtigung für Teammitglieder. Gleiche 503/analytics_unavailable-Haltung wie bei der Metrik-Reihe.
Pro Kontakt findet sich die gleiche Aufteilung unter Kontaktkosten abrufen.

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	Nur Aktivitäten einbeziehen, die zu dieser Kampagne gehören (`campaign_id` ebenfalls akzeptiert). Veraltet; bevorzugen Sie `agent_id`.
`agent_id`	Nein	Nur Aktivitäten einbeziehen, die zu diesem KI-Agenten gehören (`agentId` ebenfalls akzeptiert). Im Bereich eines Agenten wird die Kampagnen-Bestenliste nur aus den Aktivitäten dieses Agenten erstellt.
`tag_ids`	Nein	Durch Kommas getrennte Tag-IDs (`tagIds` ebenfalls akzeptiert, bis zu 25). Schränkt jeden Block auf Kontakte ein, die aktuell einen dieser Tags tragen – dieselbe „Match any“-Regel, die der Filter auf der Kontaktseite verwendet. Kombinierbar mit `campaignId` oder `agent_id`. Zeilen ohne Kontakt (Guthabenaufladungen auf Kontoebene) fallen aus einer Tag-basierten Ansicht heraus, und der `conversation_outcomes`-Block wird unter einem Tag-Bereich als `null` zurückgegeben. Gibt `400` mit `error_code: 400` zurück, wenn der Tag-Filter für das Konto nicht verfügbar ist.
`tag_match`	Nein	Wie `tag_ids` kombiniert werden (`tagMatch` ebenfalls akzeptiert): `any` (Standard – ein Kontakt benötigt einen der Tags) oder `all` (ein Kontakt benötigt jeden davon). Wird ignoriert, wenn `tag_ids` fehlt; jeder andere Wert ist ein `400`, wenn `tag_ids` vorhanden ist.
`granularity`	Nein	Bucket-Granularität nur für `metricDailyBreakdown`: `day` (Standard), `week` (montagsbasiert, wie `/analytics/series`) oder `month`. Dessen `labels` sind dann die Bucket-Starts, und der Block trägt `granularity` zurück. Jeder andere Block bleibt unberührt.

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 das gleiche Fenster, das `/analytics/summary` verwendet.
`endDate`	Nein	Bereichsende, ISO-Datum oder Datum-Uhrzeit.
`campaignId`	Nein	Nur Ereignisse zählen, die zu dieser Kampagne gehören (`campaign_id` ebenfalls akzeptiert). Veraltet; bevorzugen Sie `agent_id`.
`agent_id`	Nein	Nur Ereignisse zählen, die zu diesem KI-Agenten gehören (`agentId` ebenfalls akzeptiert).
`tag_ids`	Nein	Durch Kommas getrennte Tag-IDs (`tagIds` ebenfalls akzeptiert, bis zu 25). Nur Ereignisse zählen, deren Kontakt aktuell einen dieser Tags trägt. Kombinierbar mit `campaignId` oder `agent_id`. Ereignisse ohne Kontakt (`creditsRecharged`) werden unter einem Tag-Bereich ausgeschlossen.
`tag_match`	Nein	Wie `tag_ids` kombiniert werden (`tagMatch` ebenfalls akzeptiert): `any` (Standard) oder `all` (nur Kontakte, die jeden der Tags tragen). Wird ignoriert, wenn `tag_ids` fehlt; jeder andere Wert ist ein `400`, wenn `tag_ids` vorhanden ist.

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.
KI-Agenten-API — die Agenten, nach denen diese Zahlen gefiltert werden können.

Analytics & Reports API #

Datumsbereich #

Das truncated-Flag #

Zusammenfassung des Nachrichtenvolumens #

Kreditverbrauch #

Guthabenstand #

KI-Kosten-Rollup #

Metrik-Reihen #

Konversationsergebnisse #

Konversationskosten #

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

Guthabenstand

KI-Kosten-Rollup

Metrik-Reihen

Konversationsergebnisse

Konversationskosten

Dashboard-Einblicke

KI-Dashboard-Einblicke

Zeitstrahl der Entitätsaktivitäten

Aggregierte Ereignisanzahlen (Legacy)

Rollup für Agentur-Unterkonten

Analytics-API-Fehler

Nächste Schritte