Postal DevelopersREST API
Analytics
Weekly dashboard, per-track engagement and top-track rankings.
Engagement is aggregated from the activity log: plays, views, downloads, saves, shares and comments on your tracks and playlists, from share pages, storefronts and the app.
All endpoints need scope read:analytics.
Dashboard
GET /api/v1/analytics/dashboardThis week's summary. The same numbers the app's home page shows.
{
"thisWeek": {
"rangeLabel": "1–7 Sep",
"headline": "A busy week",
"blurb": "12 uploads, 340 views and 58 downloads.",
"uploaded": 12,
"views": 340,
"downloads": 58
},
"recentActivity": {
"totalThisWeek": 61,
"items": [
{ "id": "…", "title": "Downloaded Night Drive", "entityKey": "track", "entityId": "cm1x…", "sentAt": "…", "actor": { … } }
]
},
"tracks": { "total": 1284, "uploadedThisWeek": 12 },
"yourSound": { "genre": "Downtempo", "mood": "Warm", "totalDurationLabel": "71 h 12 m" },
"playlists": { "total": 37, "lastUpdatedAt": "…" }
}Entity stats
GET /api/v1/analytics/stats?entity=track&ids=cm1x…,cm1y…&since=2026-08-01&until=2026-09-01| Query | Type | Notes |
|---|---|---|
entity | track | playlist | Required |
ids | CSV, 1–50 | Required |
since, until | ISO 8601 | Optional range |
{
"entity": "track",
"range": { "since": "2026-08-01", "until": "2026-09-01" },
"items": [
{
"id": "cm1x…",
"name": "Night Drive",
"artist": "…",
"stats": { "plays": 120, "views": 210, "downloads": 18, "saved": 4, "shares": 6, "comments": 2 },
"total": 360
}
],
"notFound": []
}Ids that are deleted or not yours appear in notFound.
Top entities
GET /api/v1/analytics/top?metric=plays&entity=track&limit=10&since=2026-08-01| Query | Type | Notes |
|---|---|---|
metric | plays | views | downloads | saved | shares | comments | Required |
entity | track | playlist | Default track |
limit | 1–50 | Default 10 |
since, until | ISO 8601 |
{
"entity": "track",
"metric": "plays",
"range": { "since": "2026-08-01", "until": null },
"items": [
{ "id": "cm1x…", "name": "Night Drive", "artist": "…", "count": 120 }
]
}