> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beatpass.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Producer Intelligence API

> XP system, achievements, social analytics, contribution graphs, advanced charts, and real-time analytics for producers.

## Overview

The Producer Intelligence API is BeatPass's comprehensive analytics and gamification system for producers. It covers <Tooltip tip="Experience Points earned through uploads, plays, and engagement that determine a producer's level and leaderboard rank.">XP</Tooltip> tracking, achievements, social analytics, collaboration networks, contribution graphs, advanced charting, and real-time metrics.

<Info>
  **Base URL:** `https://open.beatpass.ca/api/v1/producer-intelligence`

  **Authentication:** Public endpoints (leaderboards, batch growth) use optional auth. All other endpoints require a valid Bearer token.
</Info>

***

## Rate Limits

Producer Intelligence endpoints have route-specific rate limits:

<AccordionGroup>
  <Accordion title="Public Endpoints" defaultOpen icon="globe">
    <Badge color="green" size="lg">600/min</Badge> — Leaderboard, collaboration leaderboard (cached responses)

    <Badge color="blue" size="lg">120/min</Badge> — Batch growth data (up to 100 tracks per request)

    <Badge color="purple" size="lg">1200/min</Badge> — Single track growth (prefer batch endpoint)
  </Accordion>

  <Accordion title="Authenticated Endpoints" icon="user-check">
    <Badge color="orange" size="lg">500/min</Badge> — Dashboard, XP, achievements, progress data, charts, exports

    <Badge color="gray" size="lg">120/min</Badge> — Social analytics, collaboration network, trending
  </Accordion>
</AccordionGroup>

```mermaid theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
flowchart TD
    A[Uploads & Plays] --> B[XP System]
    B --> C[Levels & Titles]
    C --> D[Achievements]
    B --> E[Leaderboards]
    A --> F[Contribution Graphs]
    A --> G[Advanced Charts]
    A --> H[Social Analytics\n& Collaboration Network]
```

***

## Dashboard & XP

### Get Dashboard Data

Comprehensive dashboard data for the authenticated producer.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/dashboard
```

### Get XP Sources

Breakdown of XP earned by source (uploads, plays, engagement, etc.).

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/xp-sources
```

### Get Producer Level

Current XP level and progress to next level.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/producer-level
```

### Get Progress Data (Combined)

Optimized combined endpoint that returns dashboard + XP + achievements in a single request. **Use this instead of multiple individual calls.**

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/progress-data
```

<Tip>
  The `progress-data` endpoint consolidates multiple API calls into one. Use it on dashboard page load to minimize requests and stay within rate limits.
</Tip>

***

## Achievements

### List Achievements

Get all achievements for the authenticated producer.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/achievements
```

### Get Achievement Details

Get details for a specific achievement.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/achievements/{achievementId}/details
```

***

## Social Analytics

All social analytics endpoints are rate limited to **120 requests/minute**.

### Social Analytics Overview

Get social engagement metrics (followers, follows, reposts, interactions).

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/social-analytics
```

### Social Activity Feed

Get the producer's recent social activity feed.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/social-activity-feed
```

### Collaboration Network

Map the producer's collaboration connections.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/collaboration-network
```

### Trending Collaborations

Get trending collaboration pairs on the platform.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/trending-collaborations
```

### Collaboration Opportunities

Get AI-suggested collaboration opportunities based on genre, style, and activity.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/collaboration-opportunities
```

***

## Track Growth

### Batch Growth Rates (Recommended)

Get local track trend rates for up to 100 tracks in a single request. **Always prefer this over individual calls.**

The response includes only tracks that are currently trending. A track must have recent BeatPass play momentum, meet minimum recent-play and distinct-listener thresholds, and outperform the previous comparison window. Tracks that are not trending are omitted from `growth_rates`.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/producer-intelligence/tracks/growth-batch
```

<Warning>
  Rate limit: 120 batch requests/minute. Each request can contain up to 100 track IDs.
</Warning>

### Single Track Growth (Legacy)

Get the local trend rate for an individual track.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/track/{trackId}/growth
```

<Note>
  This endpoint has a 1200/min rate limit, but the batch endpoint is strongly recommended for efficiency. Track trend rates are based on local BeatPass play activity, not Spotify popularity or payout contribution values.
</Note>

***

## Leaderboards (Public)

These endpoints are public and cached. Rate limit: **600 requests/minute**.

### Producer Leaderboard

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/leaderboard
```

### Collaboration Leaderboard

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/collaboration-leaderboard
```

***

## Contribution Graphs

### Artist Contribution Graph

Visualize the <Tooltip tip="A visualization showing how a producer's contribution value is distributed across their tracks.">contribution graph</Tooltip> — the contribution value distribution across an artist's tracks.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/artist/{artistId}/contribution-graph
```

### Platform Contribution Graph

Platform-wide contribution distribution.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/platform/contribution-graph
```

***

## Advanced Charts

### Track Charts

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/track/{trackId}/charts
```

### Artist Charts

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/artist/{artistId}/charts
```

### Album Charts

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/album/{albumId}/charts
```

### Dashboard Charts

Combined chart data for the dashboard view.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/dashboard/charts
```

### Analytics Insights

AI-generated insights about the producer's performance trends.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/insights
```

***

## Real-Time Analytics

### Live Analytics

Get live platform-wide analytics data.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/live-analytics
```

### Real-Time Track Metrics

Get live metrics (active listeners, recent plays) for a specific track.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/track/{trackId}/real-time
```

***

## Export & Reporting

### Export to CSV

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/producer-intelligence/export/csv
```

### Export to JSON

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/producer-intelligence/export/json
```

### Generate Report

Generate a comprehensive analytics report.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/producer-intelligence/report/generate
```

### Export Report as PDF

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/producer-intelligence/report/export-pdf
```

### Get Export Formats

List available export formats.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/export/formats
```

***

## Contribution & Payouts

<Note>
  Endpoints in the Contribution & Payouts and Subscription Payouts sections use different base paths (e.g., `/api/v1/producer/`, `/api/v1/tracks/`, `/api/v1/artist/`) rather than the `/api/v1/producer-intelligence/` prefix. Refer to each endpoint's full path as shown below.
</Note>

### Get Earnings Estimate

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer/earnings
```

### Get Track Breakdown

Detailed per-track contribution breakdown.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer/track-breakdown
```

### Get Track Contribution

Contribution value for a specific track.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/tracks/{track}/contribution
```

### Update My Contributions

Trigger a recalculation of the authenticated producer's contribution values.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/producer/update-contributions
```

### Platform Stats

Public platform-wide statistics.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/platform/stats
```

### Top Tracks

Platform-wide top tracks by contribution value.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/platform/top-tracks
```

***

## Subscription Payouts

<Info>
  These endpoints are for payout history and summary reporting. They do not set up BEATPAY, change bank details, switch payout providers, or release payouts. Producers manage payout setup in **Finances**.
</Info>

### List Payouts

Get the authenticated artist's subscription payout history.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/artist/subscription-payouts
```

### Payout Summary

Get aggregate payout summary.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/artist/subscription-payouts/summary
```

### Payout Detail

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/artist/subscription-payouts/{splitId}
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use combined endpoints" icon="layer-group">
    Use `progress-data` instead of calling `dashboard`, `xp-sources`, and `achievements` separately.
  </Accordion>

  <Accordion title="Use batch track trend endpoint" icon="bolt">
    Use `tracks/growth-batch` for up to 100 tracks per request instead of individual `track/{id}/growth` calls. Non-trending tracks are omitted from the response.
  </Accordion>

  <Accordion title="Respect cache TTLs" icon="clock">
    Leaderboard data is cached for 5 minutes. Dashboard data is cached for 15 minutes. Don't poll faster than these intervals.
  </Accordion>

  <Accordion title="Debounce real-time requests" icon="gauge">
    Real-time analytics endpoints are database-intensive. Debounce requests and use appropriate intervals (30s+).
  </Accordion>
</AccordionGroup>

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Rate Limits" icon="gauge" href="/developers/rate-limits">
    Detailed rate limiting by endpoint group.
  </Card>

  <Card title="Dashboard API" icon="chart-mixed" href="/developers/api-reference/dashboard">
    Artist dashboard metrics and profile.
  </Card>

  <Card title="Insights API" icon="chart-line" href="/developers/api-reference/insights">
    Focused insights for tracks, albums, and artists.
  </Card>

  <Card title="Search & Discovery" icon="magnifying-glass" href="/developers/api-reference/search">
    Leaderboards and discovery features.
  </Card>
</CardGroup>