Insights API

Analytics and insights endpoints for tracks, albums, and artists. Get performance data, charts, and export capabilities.

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/producer-intelligence/insights

All Insights endpoints require authentication. Include your Bearer token in the Authorization header.

---

Track Insights

Get Track Analytics

Retrieve comprehensive analytics for a track including plays, engagement, and performance metrics.

cURL

curl "https://open.beatpass.ca/api/v1/producer-intelligence/insights/tracks/123" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

const response = await fetch('/api/v1/producer-intelligence/insights/tracks/123', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
});

Parameters:

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

Response:

{
  "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/producer-intelligence/insights/tracks/{trackId}/charts?timeframe=30d

Parameters:

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/producer-intelligence/insights/tracks/{trackId}/realtime

---

Album Insights

Get Album Analytics

Retrieve analytics for an album including aggregate track performance.

GET /api/v1/producer-intelligence/insights/albums/{albumId}?period=30-days

Parameters:

Parameter	Type	Required	Description
albumId	integer	Yes	Album ID
period	string	No	Time period. Default: 30-days

Get Album Charts

GET /api/v1/producer-intelligence/insights/albums/{albumId}/charts?timeframe=30d

---

Artist Insights

Get Artist Analytics

Retrieve comprehensive analytics for an artist’s content.

GET /api/v1/producer-intelligence/insights/artists/{artistId}?period=30-days

Parameters:

Parameter	Type	Required	Description
artistId	integer	Yes	Artist ID
period	string	No	Time period. Default: 30-days

Get Artist Charts

GET /api/v1/producer-intelligence/insights/artists/{artistId}/charts?timeframe=30d

Get Collaboration Stats

Retrieve collaboration statistics and network data.

GET /api/v1/producer-intelligence/insights/artists/{artistId}/collaborations

Response:

{
  "success": true,
  "data": {
    "total_collaborations": 15,
    "top_collaborators": [...],
    "collaboration_tracks": [...]
  }
}

---

Export

Get Available Formats

List available export formats.

GET /api/v1/producer-intelligence/insights/export/formats

Response:

{
  "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/producer-intelligence/insights/export/csv
Content-Type: application/json

{
  "type": "tracks",
  "period": "30-days"
}

Export to JSON

Export analytics data as structured JSON.

POST /api/v1/producer-intelligence/insights/export/json
Content-Type: application/json

{
  "type": "tracks",
  "period": "30-days"
}

Generate Report

Generate a comprehensive analytics report.

POST /api/v1/producer-intelligence/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/producer-intelligence/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

Example Error Response:

{
  "success": false,
  "message": "Track not found",
  "error": "not_found"
}

---

Related

Authentication

Learn about API authentication.

Rate Limits

Understand API rate limits and caching.