Analytics & Reports API #

Dessa skrivskyddade slutpunkter låter dig hämta ditt kontos aktivitet till dina egna instrumentpaneler och rapporter: antal meddelandehändelser, kreditförbrukning, AI-kostnader samt samma diagram och insikter som visas i appens instrumentpanel. Denna guide täcker:

• Sammanfattning — räknare för meddelandevolym (skickade, levererade, lästa, besvarade, bokade, skapade kontakter, krediter).
• Krediter — en detaljerad, paginerad huvudbok över kreditförbrukning med summor och specifikationer.
• AI-kostnad — en daglig sammanställning av AI-utgifter.
• Metrikserier — en tidsserie redo för diagram för en eller flera mätvärden, grupperade efter kampanj, kanal, AI-agent eller nummer.
• Konversationsresultat — konversationer över tid, grupperade efter de kontakttaggar de bär (avslutande taggar som din agent tillämpar).
• Konversationskostnader: den genomsnittliga kreditkostnaden för en konversation som AI:n hanterade själv jämfört med en där ditt team klev in.
• Instrumentpanelsinsikter och AI-insikter för instrumentpanel — fullständig data bakom instrumentpanelen i appen, inklusive AI-skrivna sammanfattningar.
• Entitetsaktivitet — tidslinjen för en enskild kontakt, affär eller uppgift.
• Aggregerade händelseräknare — en äldre, camelCase-form av Sammanfattning som behållits för befintliga integrationer.

Varje slutpunkt på denna sida kräver en exakt omfattning, inte båda: skicka högst en av campaign_id (äldre) eller agent_id där slutpunkten accepterar det. Att skicka båda returnerar 400, och ett id som inte finns på ditt konto returnerar 404 istället för 403, så att andra kontons id:n förblir omöjliga att gissa.

Endast två slutpunkter filtrerar efter kontakttagg. tag_ids (med tag_match) respekteras av Dashboard insights och Aggregated event counts — det är de två som instrumentpanelens filter Alla taggar använder. Summary, Metric series och Conversation outcomes validerar parametern (en felaktig id-lista returnerar fortfarande 400) men tillämpar den inte: du får tillbaka siffror för hela kontot, utan något felmeddelande som informerar dig om detta. Läs inte en ofiltrerad totalsumma som en taggfiltrerad.

Alla sökvägar nedan är relativa till API:ets bas-URL:

https://api.youraiconnector.com/v1

Varje begäran måste autentiseras. Se Autentisering för de fyra accepterade metoderna. Exemplen här använder X-API-Key-huvudet (och en form med frågeparameter för cURL).

Datumintervall #

Alla tre slutpunkter accepterar samma valfria datumfilter:

Datum tolkas i UTC. Intervallet är som standard de senaste 30 dagarna och är begränsat till 366 dagar — ett bredare intervall returnerar 400. from får inte vara efter to.

Flaggan truncated #

Slutpunkterna Sammanfattning och Krediter begränsar hur många poster en enskild begäran skannar. Om ditt intervall är tillräckligt aktivt för att nå den gränsen, inkluderar svaret "truncated": true. När du ser detta är siffrorna baserade på en partiell skanning — begränsa ditt datumintervall (eller bläddra igenom med ett mindre fönster) för att få fullständiga siffror.

Sammanfattning av meddelandevolym #

Returnerar aggregerade räknare för meddelandehändelser för ditt konto, både som intervallsummor och som en daglig serie. Varje dag i intervallet visas i by_date — dagar utan aktivitet fylls med nollor. Filtrera valfritt till en enskild kampanj med campaign_id.

GET /analytics/summary

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

Svar

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

Varje post i by_date har samma räknarfält som totals, plus ett date.

Om du skickar ett campaign_id som inte tillhör ditt konto blir svaret 404 med { "success": false, "error": "Campaign not found" }.

Kreditförbrukning #

Returnerar kreditförbrukning över intervallet: en paginerad lista med enskilda poster, plus intervallsummor och uppdelningar per orsak och per kampanj.

GET /analytics/credits

Justeringar kontra förbrukning: Saldoförändringar såsom bonusar, abonnemangsförnyelser och korrigeringar är exkluderade från totals och uppdelningarna – de är inte faktisk förbrukning. De visas fortfarande i records-listan, markerade med "is_adjustment": true.

Summor och uppdelningar visas endast på den första sidan (när inget cursor anges). På efterföljande sidor returneras totals, by_reason, by_reason_cost och by_campaign som null – endast records-matrisen fortsätter. Detta undviker att hela intervallet skannas om för varje sida.

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.

Svar (första sidan)

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

Fältanteckningar:

• amount — krediter debiterade för posten. Noll för poster som faktureras din egen leverantörs-API-nyckel.
• is_adjustment — true för saldoförändringar (exkluderade från summor/uppdelningar).
• cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, ai_model, request_id — ifyllda endast för poster som faktureras din egen leverantörs-API-nyckel; noll eller null annars.
• is_test — true för playground/testkörningar, som aldrig faktureras.
• next_cursor — markören för nästa sida, eller null när det inte finns fler poster.

Kreditsaldo #

GET /users/me/credits — ditt kontos nuvarande kreditstatus i ett anrop: vad som finns kvar att spendera, den månatliga tilldelningen samt inställningar för automatisk påfyllning och låg kredit. Kreditförbrukningen ovan är en historik; detta är saldot just nu. Teammedlemmar som anropar detta behöver faktureringsåtkomst; kontoinnehavarens nyckel har alltid detta.

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

Svar (200)

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

Byråer kan skicka sub_account_id för att läsa ett klientkontos saldo. Inuti en automatisering returnerar steget Kontrollera krediter samma fält.

AI-kostnadssammanställning #

Returnerar AI-utgiftssammanställningen per dag för ditt konto. Detta läser föraggregerade dagliga summor, så det är snabbt även över långa intervall. Varje dag i intervallet visas i days – dagar utan aktivitet fylls med nollor.

GET /analytics/ai-cost

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

Svar

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

Fältanteckningar:

• byok_usd — utgifter som debiteras dina egna API-nycklar för leverantörer.
• platform_usd — den del av utgifterna som kördes på plattformen istället för med din egen nyckel.
• input_usd, output_usd, cache_creation_usd, cache_read_usd — kostnadskomponenterna som utgör total_usd.
• by_provider — utgifter i USD grupperade efter AI-leverantörens namn.
• USD-belopp returneras endast till konton som använder sin egen leverantörsnyckel. För konton som betalar med krediter är varje USD-fält noll och costs_redacted är true (antal anrop förblir synliga).

Metrikserier #

Returnerar en eller flera metriktidsserier i ett anrop, valfritt grupperade efter upp till två dimensioner — slutpunkten för att binda ett diagram. En enskild förfrågan kan besvara “skickade och besvarade per dag, per kanal, för denna kampanj” utan att behöva ett anrop per kampanj.

GET /analytics/series

Varje svar innehåller en labels-matris (tidsaxeln, nollfylld över hela intervallet) och en post i series per grupp, där varje post innehåller en matris per begärt mätvärde anpassad till labels. Serier efter limit tas inte bort — de kollapsar till other_bucket, beräknat som intervallsumman minus de returnerade serierna, så att ett renderat diagram alltid summerar till dina faktiska siffror; truncated är true närhelst detta inträffar.

Var siffrorna kommer ifrån: sent, delivered, read och replied kommer från meddelandeposter, som bär på kanal och avsändarnummer. booked, contact_created och credits_spent kommer från händelseströmmen, som inte bär på något avsändarnummer, så dessa mätvärden hamnar i null-nummerkategorin när du grupperar efter number.

conversations räknar de konversationer (chattsessioner) som startade i varje bucket, och conversation_credits vad dessa konversationer kostade, beräknat exakt som Konversationskostnader. Dividera det ena med det andra per bucket för att få den genomsnittliga kostnaden per konversation över tid. När du grupperar eller filtrerar efter kampanj, agent, kanal eller nummer, räknas en konversation till den som dess första meddelande tillhör.

Denna slutpunkts datumintervall är begränsat till 92 dagar (snävare än 366-dagarsgränsen som används på andra ställen på denna sida).

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

Svar

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

Fältanteckningar:

• key — identiteten för en serie. Endast nycklarna för de begärda group_by-dimensionerna finns med; en dimension vars värde är okänt för en rad (ett meddelande utan kampanj, en händelse utan kanal) kommer tillbaka som null istället för att tas bort, så att serierna fortfarande summerar till totalerna.
• other_bucket — null när ingenting kollapsades.
• Denna slutpunkt returnerar 503 med "error_code": "analytics_unavailable" när rapportdatabasen inte kan svara för ditt konto, istället för en 200 full av nollor — ett nollställt diagram skulle läsas som fakta.

Konversationsresultat #

Returnerar konversationsresultat över ett datumintervall: ett dagligt antal konversationer under varje kontakttagg, plus intervallsummor för svar, bokningar, överlämningar till en människa och konversationer vars kontakt inte bär någon tagg.

Taggen är en kontakttagg: de taggar som din AI-agent tillämpar med sitt taggverktyg, regler för autotaggning, API:et eller ditt team. Det är inte en etikett per konversation. En konversation räknas under de taggar som kontakten bär vid tidpunkten för förfrågan, så en kontakt med flera taggar räknas en gång under varje, och en tagg som tas bort senare försvinner även från tidigare dagar. Ge din agent en avslutstagg per resultat (till exempel resolved_ai, handoff_asked_for_human) så returnerar denna slutpunkt innehålls- och överlämningsorsaker över tid.

GET /analytics/outcomes

Skicka group_by=tag för att kollapsa tidsaxeln och endast få intervallsummor per tagg — i det läget är labels tom och varje taggs counts-matris är tom, medan total fortfarande är ifylld.

Detta slutpunkts datumintervall är begränsat till 92 dagar.

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

Svar

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

Fältanteckningar:

• by_tag[].tag / by_tag[].tag_id — kontakttaggens namn och id; båda är null på raden för konversationer vars kontakt inte bär någon tagg. Som mest returneras 20 taggar, med högst volym först.
• totals.sessions — distinkta konversationer som påbörjats under intervallet. Det är inte summan av by_tag[].total: en kontakt med tre taggar bidrar med en konversation till tre rader.
• totals.unresolved — konversationer vars kontakt inte bär någon tagg.
• totals.human_alerted — konversationer som överlämnats till en människa; detta skrivs vid varje överlämning och har tidigare inte visats av någon slutpunkt.
• Samma 503/analytics_unavailable-hållning som Metrikserier när rapportdatabasen inte kan svara.

Konversationskostnader #

Returnerar vad en konversation kostar i genomsnitt under ett datumintervall, uppdelat efter hur den gick. Detta är siffran att visa en kund som avkastning på investeringen: vad en konversation som AI:n hanterade själv kostar, jämfört med en som ditt team var tvunget att kliva in i.

GET /analytics/conversation-costs

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

Svar

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

Fältanteckningar:

• Räknar konversationer (chattsessioner) som startade inom intervallet, med krediter debiterade inom varje konversationsfönster, minus återbetalningar. Krediter som förbrukats utanför en konversation (dagliga sammanfattningar, månadsavgifter, automatiseringar som inte startades av en kontakt, såsom webhook- eller RSS-utlösare) ingår inte. Automatiseringskörningar och AI-steg som startats av en kontakt räknas till kontaktens konversation sedan den 26 september 2026.
• contained: AI:n svarade och ingen från ditt team behövde ingripa. handed_off: någon skickade ett meddelande efter att AI:n hade svarat, eller så larmade AI:n en människa. no_ai: AI:n svarade aldrig (till exempel chattar som ditt team hanterar med AI:n pausad).
• Högst 20 000 konversationer räknas; sessions_truncated är true när intervallet innehöll fler, så begränsa det.
• Kräver faktureringsbehörighet för teammedlemmar. Samma 503/analytics_unavailable-inställning som för mätvärdesserier.
• Per kontakt finns samma uppdelning under Hämta kontaktkostnad.

Instrumentpanelsinsikter #

Returnerar hela instrumentpanelens nyttolast för ett datumintervall i ett anrop: en värmekarta för svarsfrekvens per veckodag och timme, kampanjtopplista, volym per kanal, exakta totaler per anslutning, mätvärdesuppdelningar per dag (kontoomfattande, per kanal och per nummer), var kontakter kommer ifrån, svarstid i inkorgen och ett flöde med nyligen utförda aktiviteter. Detta är den mest omfattande rapporteringsnyttolasten i API:et — den driver instrumentpanelen i appen direkt.

GET /analytics/dashboard-insights

Denna slutpunkt använder startDate/endDate (inte from/to) eftersom den delar implementering med instrumentpanelen i appen. Intervallet är begränsat till 92 dagar och justeras, avvisas inte, när det är bredare.

Null betyder otillgänglig, inte noll. Flera block (numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry) beräknas från rapporteringsdatabasen och returneras som null när den inte kan svara för ditt konto. Rendera inte ett null-block som ett tomt diagram.

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

Svar (förkortat — denna nyttolast är stor; se API-referensen för det fullständiga schemat)

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

Fältanteckningar:

• heatmap.buckets[].weekday — 0 är söndag till 6 är lördag.
• numberStats, channelDailySeries, metricDailyBreakdown, contactsByCountry, ai_human_split — var och en oberoende null när rapporteringsdatabasen är otillgänglig för ditt konto; alla andra block returneras fortfarande.

AI-insikter för instrumentpanel #

Returnerar tre korta, AI-skrivna insikter om kontots meddelandehantering under ett datumintervall: en vinst, en sak att hålla koll på och ett tips — meningar som du kan klistra in direkt i en rapport istället för siffror som du fortfarande måste tolka. Genereras endast från kontots egna meddelandemätvärden.

GET /analytics/dashboard-ai-insights

Denna slutpunkt gäller hela kontot — den kräver inget omfång för kampanj eller agent.

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

Svar

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

Saknad startDate eller endDate returnerar 400.

Tidslinje för entitetsaktivitet #

Returnerar en enskild kontakts, affärs eller uppgifts aktivitet som en tidslinje, med det senaste först: vad som hände och när, fördelat på meddelanden, möten, anteckningar och statusändringar. Använd den för att besvara “vad har hänt med den här personen” utan att behöva kombinera flera list-slutpunkter.

GET /analytics/entity-activity

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

Svar

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

En saknad eller ogiltig entityType/entityId returnerar 400. En entitet som inte finns på ditt konto returnerar 404, så att andra kontons ID:n förblir omöjliga att gissa.

Aggregerade händelseantal (äldre) #

Returnerar samma aggregerade händelseantal som Sammanfattning av meddelandevolym, men i camelCase-format (contactCreated istället för contact_created, byDate istället för by_date) som vissa äldre integrationer byggdes mot. Föredra /analytics/summary för nya integrationer — denna slutpunkt finns endast för att instrumentpanelen i appen och API:et ska dela en implementering.

GET /analytics/aggregate

cURL

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

Svar

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

Sammanställning för byråns underkonton #

Analytics API-fel #

Analytics-slutpunkter returnerar standardfelkuvertet:

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

På en analys-slutpunkt returnerar ett ogiltigt datumformat eller ett fönster utanför intervallet 400, och ett okänt campaign_id eller agent_id returnerar 404. Att skicka både campaign_id och agent_id till en slutpunkt som accepterar något av dem är också ett 400 — skicka högst ett. De PG-specifika rapport-slutpunkterna (Metrikserier, Konversationsresultat, Byråsammanställning) returnerar 503 med "error_code": "analytics_unavailable" istället för en 200 full av nollor när rapportdatabasen inte kan svara för ditt konto — försök igen om en stund. De delade koderna som alla slutpunkter kan returnera — 401, 403 (din plan inkluderar inte API-åtkomst, eller, vid byråsammanställning, är ditt konto inte Agency/Dev), 429 (hastighetsbegränsning) och 500 — listas med vägledning för att försöka igen i Fel & Paginering.

Nästa steg #

• Autentisering — de fyra sätten att autentisera en begäran.
• Fel och hastighetsbegränsningar — statuskoder och gränsen på 300 förfrågningar/min.
• AI-agent-API — de agenter som dessa siffror kan filtreras efter.