# Missed call analytics

`GET /analytics/missed-calls`

Returns the missed call statistics of one shop (`shop_id`) or all your
shops over a period: total calls, SMS sent, SMS delivered, SMS blocked
(rate limited), the evolution over time at the requested `granularity`,
and the comparison with the previous period of identical duration.

Requires the `missed_calls:read` scope.

**Returns** a single object (no pagination). Test calls made from the
configuration screen are excluded. All figures are zero when the period
holds no call.

## Example request

```bash
curl "https://api.dokaa.app/v1/analytics/missed-calls?from=FROM&to=TO" \
  -H "Authorization: Bearer dk_live_..."
```

## Query parameters

- `shop_id` (string) – Restrict to a single shop (omit to query all your shops)
- `from` (string, required) (format: date) – First day of the period (UTC)
- `to` (string, required) (format: date) – Last day of the period (UTC)
- `granularity` (string) (default: day; one of: hour, day, week, month) – Bucket size of the `evolution` series. The allowed span depends on the granularity: 31 days for `hour`, 366 for `day`, 1095 for `week`, 3660 for `month`; larger ranges answer a `422` problem.

## Responses

### 200 – Missed call aggregates, evolution and previous-period comparison

```json
{
  "period": {
    "from": "2026-07-01",
    "to": "2026-08-05"
  },
  "granularity": "day",
  "total_calls": 40,
  "sms_sent": 30,
  "sms_delivered": 25,
  "sms_blocked": 5,
  "previous_total_calls": 20,
  "previous_sms_sent": 10,
  "previous_sms_blocked": 10,
  "calls_delta": 20,
  "sms_sent_delta": 20,
  "sms_blocked_delta": -5,
  "calls_evolution": 100,
  "sms_sent_evolution": 200,
  "sms_blocked_evolution": -50,
  "evolution": [
    {
      "date": "2026-07-01",
      "calls": 8,
      "sms_sent": 6,
      "sms_blocked": 1
    }
  ]
}
```

### 401 – Missing, invalid, or revoked API key

### 403 – The API key does not grant access to this resource

### 422 – Invalid request parameters

Errors are `application/problem+json` (RFC 9457) with `type`, `title`, `status` and `detail` fields.