Skip to main content

​
Overview

The Artist Dashboard API provides programmatic access to producer analytics displayed in the Producer Dashboard. These endpoints return plays, followers, upload insights, and collaboration data for authenticated producers.
Base URL: https://open.beatpass.ca/api/v1Authentication: All endpoints require a valid Bearer token. The user must have a producer profile (be linked to an artist).

​
Authentication Requirements

All dashboard endpoints require:
  • Authentication: User must include a valid Bearer token
  • Producer profile: User must have an associated artist profile (created via the Producer Program)
  • Upload access: Some endpoints (upload insights) additionally require the artist profile to have upload access enabled

​
Response Format

All Dashboard API responses use a standard envelope: 
{
  "success": true,
  "data": { ... }
}
On error, the envelope contains: 
{
  "success": false,
  "message": "Error description"
}

​
Endpoints

​
Artist Profile Summary

Endpoint: GET /api/v1/artist/profile Returns the active artist profile associated with the authenticated user.

​
Response Fields

​
id
integer
required
Artist ID associated with the current user.
​
name
string
required
Artist display name.
​
upload_access
boolean
required
Whether the profile can upload/manage tracks (gates upload health widgets).
​
total_tracks
integer
required
Count of tracks linked to the artist.
​
total_plays
integer
required
Aggregate plays across all linked tracks.
​
member_since
string
required
ISO timestamp when the artist profile was created.
​
bio
string
Current bio text.
​
website
string
Website URL if set.
​
social_links
object
Social handles/URLs (twitter, instagram, soundcloud, youtube).

​
Update Artist Profile

Endpoint: PUT /api/v1/artist/profile Update the authenticated artist’s profile information.

​
Request Body

​
bio
string
Artist bio text. Max 1,000 characters.
​
website
string
Website URL (must be a valid URL). Max 255 characters.
​
social_links
object
Social media handles/URLs.

​
Response

{
  "success": true,
  "message": "Profile updated successfully",
  "data": {
    "bio": "Updated bio text",
    "website": "https://example.com",
    "social_links": {
      "twitter": "@producer",
      "instagram": "@producer"
    }
  }
}

​
Dashboard Stats

Endpoint: GET /api/v1/artist/dashboard-stats Retrieves headline metrics used on the Backstage dashboard.

​
Response Fields

​
total_tracks
integer
required
How many tracks the artist has published.
​
total_plays
integer
required
Total lifetime plays.
​
total_contribution
number
required
Sum of contribution values across tracks (used for earnings splits).
​
recent_uploads
integer
required
Tracks uploaded in the last 30 days.
​
play_growth_percentage
number
required
Month-over-month play growth percentage.
​
top_track
object
​
average_plays_per_track
integer
required
Rounded average plays per track.
​
tracks_with_plays
integer
required
How many tracks have at least one play.

​
Track Performance

Endpoint: GET /api/v1/artist/track-performance Returns the most recent 20 tracks with their performance signals for timeline charts.

​
Response Fields (Array)

​
[].track_id
integer
required
Track ID.
​
[].track_name
string
required
Track title.
​
[].plays
integer
required
Total plays for the track.
​
[].contribution_value
number
required
Contribution value for the track.
​
[].months_since_upload
integer
required
Age of the track in months (used for cohorting performance).
​
[].upload_date
string
required
Upload timestamp.
​
[].last_updated
string
When contribution was last recalculated (null if pending).

​
Upload Insights

Endpoint: GET /api/v1/artist/upload-insights Provides upload cadence analysis and recommendations for optimal release timing.

​
Response Fields

​
total_uploads
integer
required
Total tracks uploaded by the artist.
​
uploads_this_month
integer
required
Uploads in the current calendar month.
​
uploads_last_month
integer
required
Uploads in the previous calendar month.
​
average_plays_per_upload
integer
required
Rounded average plays per upload.
​
best_performing_month
object
​
upload_frequency_days
integer
Average days between uploads (null when fewer than two uploads exist).
​
recommended_upload_time
string
required
Text recommendation for how often to upload next.
Returns 403 Forbidden if upload_access is false on the artist profile.

​
Collaborative Tracks

Endpoint: GET /api/v1/artist/{artist}/collaborative-tracks Retrieves tracks where the artist has collaborated with other producers.

​
Path Parameters

​
artist
integer
required
Artist ID to fetch collaborations for.

​
Response Fields (Array)

​
[].track_id
integer
required
Collaborative track ID.
​
[].title
string
required
Track name.
​
[].primary_artist
string
required
Primary artist credit.
​
[].collaborators
array
required
List of collaborating artists on the track.
​
[].plays
integer
Play count for the collaborative track.

​
Integration Example

// Example: Fetch dashboard stats for authenticated producer
async function getDashboardStats() {
  const response = await fetch('https://open.beatpass.ca/api/v1/artist/dashboard-stats', {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN_HERE'
    }
  });
  
  if (!response.ok) {
    throw new Error(`Dashboard API error: ${response.status}`);
  }
  
  const stats = await response.json();
  return stats;
}

Authentication

Understand API authentication

Rate Limits

Understand API rate limiting

Error Handling

Handle API errors properly

API Reference

Browse the OpenAPI reference
Last modified on February 7, 2026