Overview
The Insights API provides focused, domain-specific analytics endpoints for content creators. These endpoints offer comprehensive analytics data, charts, and export capabilities.
Base URL: https://open.beatpass.ca/api/v1/insights
All Insights endpoints require authentication. Include session cookies in your requests.
Track Insights
Get Track Analytics
Retrieve comprehensive analytics for a track including plays, engagement, and performance metrics.
curl "https://open.beatpass.ca/api/v1/insights/tracks/123" \
-H "Accept: application/json" \
--cookie "session=..."
| Parameter | Type | Required | Description |
|---|
trackId | integer | Yes | Track ID |
period | string | No | Time period: 7-days, 30-days, 90-days, 1-year. Default: 30-days |
{
"success": true,
"data": {
"plays": { "total": 1250, "period": 340 },
"listeners": { "total": 890, "unique": 456 },
"engagement": { "likes": 78, "reposts": 12 },
"growth": { "plays_change": 15.2, "listeners_change": 8.4 }
}
}
Get Track Charts
Retrieve chart data for visualizing track performance over time.
GET /api/v1/insights/tracks/{trackId}/charts?timeframe=30d
| Parameter | Type | Description |
|---|
trackId | integer | Track ID |
timeframe | string | Chart timeframe: 7d, 30d, 90d, 1y |
Get Real-Time Metrics
Get live metrics for a track (active listeners, recent plays).
GET /api/v1/insights/tracks/{trackId}/realtime
Album Insights
Get Album Analytics
Retrieve analytics for an album including aggregate track performance.
GET /api/v1/insights/albums/{albumId}?period=30-days
| Parameter | Type | Required | Description |
|---|
albumId | integer | Yes | Album ID |
period | string | No | Time period. Default: 30-days |
Get Album Charts
GET /api/v1/insights/albums/{albumId}/charts?timeframe=30d
Artist Insights
Get Artist Analytics
Retrieve comprehensive analytics for an artist’s content.
GET /api/v1/insights/artists/{artistId}?period=30-days
| Parameter | Type | Required | Description |
|---|
artistId | integer | Yes | Artist ID |
period | string | No | Time period. Default: 30-days |
Get Artist Charts
GET /api/v1/insights/artists/{artistId}/charts?timeframe=30d
Get Collaboration Stats
Retrieve collaboration statistics and network data.
GET /api/v1/insights/artists/{artistId}/collaborations
{
"success": true,
"data": {
"total_collaborations": 15,
"top_collaborators": [...],
"collaboration_tracks": [...]
}
}
Export
List available export formats.
GET /api/v1/insights/export/formats
{
"success": true,
"formats": [
{ "id": "csv", "name": "CSV", "description": "..." },
{ "id": "json", "name": "JSON", "description": "..." },
{ "id": "pdf", "name": "PDF Report", "description": "..." }
]
}
Export to CSV
Export analytics data as CSV.
POST /api/v1/insights/export/csv
Content-Type: application/json
{
"type": "tracks",
"period": "30-days"
}
Export to JSON
Export analytics data as structured JSON.
POST /api/v1/insights/export/json
Content-Type: application/json
{
"type": "tracks",
"period": "30-days"
}
Generate Report
Generate a comprehensive analytics report.
POST /api/v1/insights/export/report
Content-Type: application/json
{
"period": "30-days",
"include_charts": true
}
Export PDF
Export the report as a PDF document.
POST /api/v1/insights/export/pdf
Content-Type: application/json
{
"period": "30-days"
}
Error Responses
All Insights endpoints use standardized error responses:
| Status | Error | Description |
|---|
| 401 | unauthorized | Authentication required |
| 403 | forbidden | Access denied to this resource |
| 404 | not_found | Resource not found |
| 422 | validation_failed | Invalid parameters |
| 500 | server_error | Internal server error |
{
"success": false,
"message": "Track not found",
"error": "not_found"
}
Migration from Legacy Endpoints
The Insights API replaces the legacy content analytics endpoints:
| Legacy Endpoint | New Endpoint |
|---|
GET /content-analytics/track/{id} | GET /insights/tracks/{id} |
GET /content-analytics/album/{id} | GET /insights/albums/{id} |
GET /content-analytics/artist/{id} | GET /insights/artists/{id} |
POST /content-analytics/export/csv | POST /insights/export/csv |
Legacy endpoints are deprecated and will be removed in a future version.
