Dashboard API Integration

Integrate BeatPass dashboard metrics using the Artist Dashboard API endpoints. Retrieve plays, followers, upload insights, and collaboration data.

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/v1

Authentication: 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.

Show Social links fields

social_links.twitter · string

Twitter/X handle or URL. Max 255 characters.

social_links.instagram · string

Instagram handle or URL. Max 255 characters.

social_links.soundcloud · string

SoundCloud profile URL. Max 255 characters.

social_links.youtube · string

YouTube channel URL. Max 255 characters.

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

Show Top track object

id · integer · required

Track ID with the most plays.

name · string · required

Track name.

plays · integer · required

Play count for the top track.

contribution_value · number · required

Contribution value for the top track.

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

Show Best performing month object

month · string · required

Month key in YYYY-MM format.

total_plays · integer · required

Total plays earned that month.

track_count · integer · required

Number of tracks uploaded that month.

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;
}

---

Related Resources

Authentication

Understand API authentication

Rate Limits

Understand API rate limiting

Error Handling

Handle API errors properly

API Reference

Browse the OpenAPI reference