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 diagramfärdig tidsserie för en eller flera mätvärden, grupperade efter kampanj, kanal, AI-agent eller nummer.
- Konversationsresultat — hur konversationer avslutades, baserat på AI-tilldelade resultattaggar.
- Instrumentpanelsinsikter och AI-insikter för instrumentpanel — den fullständiga datan bakom instrumentpanelen i appen, inklusive AI-skrivna sammanfattningar.
- Entitetsaktivitet — tidslinjen för en enskild kontakt, affär eller uppgift.
- Aggregerade händelseantal — 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.
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:
| Parameter | Beskrivning |
|---|---|
from |
Start för intervallet, YYYY-MM-DD, inklusive. Standard är 30 dagar sedan. |
to |
Slut för intervallet, YYYY-MM-DD, inklusive. Standard är idag. |
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.
Obs: Kostnads- och tokensiffror inkluderas endast för AI-anrop som faktureras via dina egna API-nycklar för leverantörer. När kostnadssiffror är dolda för ditt konto anger svaret "costs_redacted": true och kostnadsfälten returneras som noll.
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
| Parameter | Krävs | Beskrivning |
|---|---|---|
from |
Nej | Intervallstart, YYYY-MM-DD. |
to |
Nej | Intervallslut, YYYY-MM-DD. |
campaign_id |
Nej | Räkna endast händelser som tillhör denna kampanj. |
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
| Parameter | Krävs | Beskrivning |
|---|---|---|
from |
Nej | Intervallstart, YYYY-MM-DD. |
to |
Nej | Intervallslut, YYYY-MM-DD. |
campaign_id |
Nej | Inkludera endast förbrukning som tillskrivs denna kampanj. |
limit |
Nej | Sidstorlek för records, 1–100. Standard är 50. |
cursor |
Nej | Skicka föregående sidas next_cursor för att hämta nästa sida. |
Justeringar kontra förbrukning: Saldoförändringar såsom bonusar, abonnemangsförnyelser och korrigeringar är exkluderade från
totalsoch uppdelningarna – de är inte faktisk förbrukning. De visas fortfarande irecords-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—truefö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 ellernullannars.is_test—trueför playground/testkörningar, som aldrig faktureras.next_cursor— markören för nästa sida, ellernullnär det inte finns fler poster.
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
| Parameter | Krävs | Beskrivning |
|---|---|---|
from |
Nej | Intervallstart, YYYY-MM-DD. |
to |
Nej | Intervallslut, 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()
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örtotal_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ärtrue(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.
| Parameter | Krävs | Beskrivning |
|---|---|---|
from |
Nej | Intervallstart, YYYY-MM-DD. Standard är 30 dagar sedan. |
to |
Nej | Intervallslut, YYYY-MM-DD. Standard är idag. |
metrics |
Nej | Komma-separerad lista från sent, ai_sent, human_sent, delivered, read, replied, booked, contact_created, credits_spent. Standard är sent,replied. Ett okänt mätvärde returnerar 400. |
group_by |
Nej | Komma-separerad lista med upp till två dimensioner från date, campaign, channel, agent, number. date accepteras men har ingen effekt — varje svar innehåller redan tidsaxeln. Utelämna för en enskild kontoomfattande serie. |
granularity |
Nej | day (standard), week eller month. Veckokategorier börjar på måndagar, månadskategorier den 1:a. |
limit |
Nej | Hur många serier som ska returneras innan resten kollapsar till other_bucket, 1–50. Standard är 12. |
campaign_id |
Nej | Räkna endast aktivitet som tillhör denna kampanj. Äldre; föredra agent_id. |
agent_id |
Nej | Räkna endast aktivitet som tillhör denna AI-agent. |
channel |
Nej | Räkna endast aktivitet på denna kanal, till exempel whatsapp. |
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ärdagroup_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 somnullistället för att tas bort, så att serierna fortfarande summerar till totalerna.other_bucket—nullnär ingenting kollapsades.- Denna slutpunkt returnerar
503med"error_code": "analytics_unavailable"när rapportdatabasen inte kan svara för ditt konto, istället för en200full av nollor — ett nollställt diagram skulle läsas som fakta.
Konversationsresultat
Returnerar hur konversationer avslutades under ett datumintervall: ett dagligt antal för varje resultattagg som AI:n tilldelat, plus intervallsummor för svar, bokningar, överlämningar till en människa och konversationer som AI:n aldrig klassificerade.
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.
| Parameter | Krävs | Beskrivning |
|---|---|---|
from |
Nej | Intervallstart, YYYY-MM-DD. Standard är 30 dagar sedan. |
to |
Nej | Intervallslut, YYYY-MM-DD. Standard är idag. |
campaign_id |
Nej | Räkna endast konversationer med kontakter som för närvarande ingår i denna kampanj. Äldre; föredra agent_id. |
agent_id |
Nej | Räkna endast resultat som tillhör denna AI-agent. |
group_by |
Nej | date (standard) behåller antalet per dag; tag summerar till intervalltotaler. |
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": "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
}
}
Fältanteckningar:
by_tag[].tag—nullför konversationer som AI:n aldrig tilldelade en resultattagg.totals.human_alerted— konversationer som överlämnats till en människa; detta skrivs vid varje överlämning och visades tidigare inte av någon slutpunkt.- Samma
503/analytics_unavailable-hållning som Metric-serien när rapporteringsdatabasen inte kan svara.
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
| Parameter | Krävs | Beskrivning |
|---|---|---|
startDate |
Ja | Intervallstart, YYYY-MM-DD. |
endDate |
Ja | Intervallslut, YYYY-MM-DD. |
campaignId |
Nej | Inkludera endast aktivitet som tillhör denna kampanj (campaign_id accepteras också). Äldre; föredra agent_id. |
agent_id |
Nej | Inkludera endast aktivitet som tillhör denna AI-agent (agentId accepteras också). Under en agentomfattning byggs kampanjtopplistan endast från den agentens aktivitet. |
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 somnullnär den inte kan svara för ditt konto. Rendera inte ettnull-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 till6är lördag.numberStats,channelDailySeries,metricDailyBreakdown,contactsByCountry,ai_human_split— var och en oberoendenullnä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
| Parameter | Krävs | Beskrivning |
|---|---|---|
startDate |
Ja | Intervallstart, YYYY-MM-DD. |
endDate |
Ja | Intervallslut, YYYY-MM-DD. |
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
| Parameter | Krävs | Beskrivning |
|---|---|---|
entityType |
Ja | contact, deal eller task. |
entityId |
Ja | ID för posten vars tidslinje ska returneras. |
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
| Parameter | Krävs | Beskrivning |
|---|---|---|
startDate |
Nej | Intervallstart, ISO-datum eller datum-tid. Standardvärdet är samma fönster som /analytics/summary använder. |
endDate |
Nej | Intervallslut, ISO-datum eller datum-tid. |
campaignId |
Nej | Räkna endast händelser som tillhör denna kampanj (campaign_id accepteras också). Äldre; föredra agent_id. |
agent_id |
Nej | Räkna endast händelser som tillhör denna AI-agent (agentId accepteras också). |
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 förfrågan.
- Fel & hastighetsbegränsningar — statuskoder och gränsen på 300 förfrågningar/min.
- Kampanj-API — kampanjerna som dessa siffror kan filtreras efter.