# 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](authentication.md) 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.

::: note
**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**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Svar**

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

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 `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**

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

**JavaScript**

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

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

**Python**

```python
import requests

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

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

**Svar** (första sidan)

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

**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.

---

## 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**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Svar**

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

**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`.

| 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**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Svar**

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

**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 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**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Svar**

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

**Fältanteckningar:**

- `by_tag[].tag` — `null` fö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 som `null` när den inte kan svara för ditt konto. Rendera inte ett `null`-block som ett tomt diagram.

**cURL**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Svar** (förkortat — denna nyttolast är stor; se [API-referensen](reference.md) för det fullständiga schemat)

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

**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`

| 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**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Svar**

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

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**

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

**JavaScript**

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

**Python**

```python
import requests

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

**Svar**

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

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](#message-volume-summary), 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**

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

**Svar**

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

---

## Sammanställning för byråns underkonton


---

## Analytics API-fel

Analytics-slutpunkter returnerar standardfelkuvertet:

```json
{
  "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](errors-and-pagination.md).

---

## Nästa steg

- [Autentisering](authentication.md) — de fyra sätten att autentisera en förfrågan.
- [Fel & hastighetsbegränsningar](errors-and-pagination.md) — statuskoder och gränsen på 300 förfrågningar/min.
- [Kampanj-API](campaigns.md) — kampanjerna som dessa siffror kan filtreras efter.