Analytics

Retrieve daily push notification statistics for an app. Use analytics data to track delivery performance, subscriber growth, and engagement trends over time.

Base URL: https://app.krafter.dev/api/v1

Get Daily Stats

Retrieve aggregated daily statistics for a date range. Each entry includes notification delivery metrics and subscriber activity.

GET /push/apps/:app_id/analytics?start_date=...&end_date=...

Required scope: push:read

Query Parameters

Both parameters are optional. Omitted or unparseable dates fall back to defaults — there is no 400 error for missing/malformed dates (push_controller.ex:291-292, 536-545).

Parameter	Type	Default	Description
start_date	string	today − 30 days	Start date in ISO 8601 format (e.g., 2025-01-01).
end_date	string	today (UTC)	End date in ISO 8601 format (e.g., 2025-01-31).

Example Request

curl "https://app.krafter.dev/api/v1/push/apps/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/analytics?start_date=2025-01-10&end_date=2025-01-15" \
  -H "Authorization: Bearer kr_live_abc123def456"

Example Response

{
  "data": [
    {
      "date": "2025-01-15",
      "sent": 100,
      "delivered": 0,
      "clicked": 50,
      "failed": 5,
      "new_subscribers": 10,
      "unsubscribes": 2
    },
    {
      "date": "2025-01-14",
      "sent": 85,
      "delivered": 0,
      "clicked": 42,
      "failed": 5,
      "new_subscribers": 8,
      "unsubscribes": 1
    },
    {
      "date": "2025-01-13",
      "sent": 120,
      "delivered": 0,
      "clicked": 63,
      "failed": 5,
      "new_subscribers": 15,
      "unsubscribes": 3
    },
    {
      "date": "2025-01-12",
      "sent": 90,
      "delivered": 0,
      "clicked": 38,
      "failed": 3,
      "new_subscribers": 6,
      "unsubscribes": 0
    },
    {
      "date": "2025-01-11",
      "sent": 110,
      "delivered": 0,
      "clicked": 55,
      "failed": 5,
      "new_subscribers": 12,
      "unsubscribes": 1
    },
    {
      "date": "2025-01-10",
      "sent": 75,
      "delivered": 0,
      "clicked": 30,
      "failed": 3,
      "new_subscribers": 5,
      "unsubscribes": 0
    }
  ]
}

Response Fields

Field	Type	Description
date	string	Date in YYYY-MM-DD format.
sent	integer	Total notifications sent (counts deliveries with status sent, delivered, or clicked per push_stats_aggregator.ex:35-41).
delivered	integer	Always 0 today. The dispatcher writes status: "sent" after the provider accepts the push (push_delivery_worker.ex:112); no current code path promotes a delivery to status: "delivered", so the aggregator's CASE WHEN ? = 'delivered' filter never matches.
clicked	integer	Notifications clicked by subscribers. Populated only when POST /push/notifications/:notification_id/track is called server-side (the endpoint requires push:write — see Track Click for the auth caveat).
failed	integer	Notifications that failed to deliver (provider rejection, expired token, etc.).
new_subscribers	integer	New subscribers registered on this date.
unsubscribes	integer	Subscribers removed on this date.

delivered is currently a no-op counter

Provider acknowledgment is treated as "sent", not "delivered" — there is no FCM/APNs/Web Push receipt callback wired up that would later flip the row to status: "delivered". Treat the delivered field as reserved; for now use sent − failed as your delivery proxy.