> ## 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.

# 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.

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

<Note>
  All Insights endpoints require authentication. Include your Bearer token in the `Authorization` header.
</Note>

***

## Track Insights

### Get Track Analytics

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

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl "https://open.beatpass.ca/api/v1/producer-intelligence/insights/tracks/123" \
    -H "Accept: application/json" \
    -H "Authorization: Bearer YOUR_TOKEN_HERE"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const response = await fetch('/api/v1/producer-intelligence/insights/tracks/123', {
    headers: {
      'Accept': 'application/json',
      'Authorization': 'Bearer YOUR_TOKEN_HERE'
    }
  });
  ```
</CodeGroup>

**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:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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).

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

***

## Album Insights

### Get Album Analytics

Retrieve analytics for an album including aggregate track performance.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/insights/albums/{albumId}/charts?timeframe=30d
```

***

## Artist Insights

### Get Artist Analytics

Retrieve comprehensive analytics for an artist's content.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET /api/v1/producer-intelligence/insights/artists/{artistId}/charts?timeframe=30d
```

### Get Collaboration Stats

Retrieve collaboration statistics and network data.

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

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": true,
  "data": {
    "total_collaborations": 15,
    "top_collaborators": [...],
    "collaboration_tracks": [...]
  }
}
```

***

## Export

### Get Available Formats

List available export formats.

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

**Response:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /api/v1/producer-intelligence/insights/export/json
Content-Type: application/json

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

### Generate Report

Generate a comprehensive analytics report.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:**

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "success": false,
  "message": "Track not found",
  "error": "not_found"
}
```

***

## Related

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developers/auth">
    Learn about API authentication.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/developers/rate-limits">
    Understand API rate limits and caching.
  </Card>
</CardGroup>