Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

API REFERENCE

Read artist player fans

On this page
GET/api/players/{id}/fans

Artist-level Spotify fan relationships across releases in the authorized workspace. Each row keeps its stable relationship id and adds contact_id, the workspace-owned contact shared across artist relationships. Email/display_name come from the latest available confirmed workspace contact profile. scope=artist_in_workspace; marketingConsent=false. No provider tokens or cross-workspace identity links. MCP: get_release_player_fans.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/players/YOUR_ID/fans' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request GET \
  --url 'https://recoup-api.vercel.app/api/players/{id}/fans'

Parameters

Path parameters

idstringrequired

Query parameters

organizationIdstring | null
offsetinteger

Default: 0

limitinteger

Default: 50

Responses

200PlayerFansResponse fields returned by the release player service.

application/json

fansarray<PlayerFan>required
Item properties for fans
idstringrequired

format: uuid

providerstringrequired
emailstring | null
display_namestring | null
first_connected_atstringrequired

format: date-time

last_connected_atstringrequired

format: date-time

contact_idstringrequired

Workspace-owned contact shared across this fan’s artist relationships.

format: uuid

scopestringrequired
marketingConsentbooleanrequired
offsetintegerrequired

format: int64

limitintegerrequired

format: int64

400Invalid input

application/json

errorstringrequired
statusstring
401Missing/invalid authentication or failed provider authorization

application/json

errorstringrequired
statusstring
403Workspace, origin, or session access denied

application/json

errorstringrequired
statusstring
404Player not available

application/json

errorstringrequired
statusstring
429Request rate limit exceeded

application/json

errorstringrequired
statusstring
503Feature/configuration temporarily unavailable

application/json

errorstringrequired
statusstring

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download players.json
View operation source
json
{
  "summary": "Read artist player fans",
  "description": "Artist-level Spotify fan relationships across releases in the authorized workspace. Each row keeps its stable relationship id and adds contact_id, the workspace-owned contact shared across artist relationships. Email/display_name come from the latest available confirmed workspace contact profile. scope=artist_in_workspace; marketingConsent=false. No provider tokens or cross-workspace identity links. MCP: get_release_player_fans.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "organizationId",
      "in": "query",
      "schema": {
        "type": [
          "string",
          "null"
        ],
        "format": "uuid",
        "description": "Authorized workspace; omit for the authenticated account. Never send account_id."
      }
    },
    {
      "name": "offset",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 100000,
        "default": 0
      }
    },
    {
      "name": "limit",
      "in": "query",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 50
      }
    }
  ],
  "responses": {
    "200": {
      "description": "PlayerFansResponse fields returned by the release player service.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerFansResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "401": {
      "description": "Missing/invalid authentication or failed provider authorization",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "403": {
      "description": "Workspace, origin, or session access denied",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "404": {
      "description": "Player not available",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "429": {
      "description": "Request rate limit exceeded",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    },
    "503": {
      "description": "Feature/configuration temporarily unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PlayerError"
          }
        }
      }
    }
  }
}