Understanding Bot Detection

artist.tools offers robust detection of artificially inflated Spotify activity, helping you understand whether a playlist, track, artist, or curator is likely involved in botted behavior. This guide explains the fields you'll see in our API, how to interpret them, and where they apply.

Entity-Specific Bot Detection

Entity Type	Key Detection Fields
Playlists	qualityScore, qualityData
Tracks/Artists	playlistSummary
All Entities	bot-status endpoint

---

Playlist-Level Detection

qualityScore (integer)

A score from -1000 to 1000 representing the playlist's estimated quality.

Score Range	Meaning
900–1000	Human-reviewed and confirmed as authentic.
1–899	No signs of botting, playlist appears active.
0	Insufficient data.
-1 to -49	No signs of botting, but low engagement or inactivity.
-50 to -899	Potentially botted (algorithmic flags, no manual review).
-900 to -1000	Confirmed botted or linked to known botted networks.

qualityData (object)

Returned for playlists only. This object contains:

• botted: true if qualityScore <= -50
• fraudData: Dates with fraud indicators (e.g. spikes, dips)
• fraudDates: Raw list of suspicious dates (deprecated)
• ignoreDates: Dates ignored due to known anomalies (e.g. mass Spotify bot purges) (deprecated)
• indicators: Tags like unusual_growth, fake_follower_ratio
• override: Manual admin-reviewed object with fields like:
  • rating: "Good", "Okay", or "Bad"
  • notes, listeners, date

---

Track/Artist-Level Detection

playlistSummary (object)

Summarizes a track or artist's exposure to playlists, including potential bot placements:

ts

playlistSummary: {
  total: number;              // Total number of playlists the entity is in
  followerReach: number;      // Combined followers across those playlists
  fraud: number;              // Count of botted playlists
  fraudSpotifyIds: string[];  // Spotify playlist IDs flagged as botted
}

Use this to quickly evaluate the overall risk associated with playlist placements.

---

All Entities: bot-status Endpoint

The /v2/misc/bot-status endpoint returns a lightweight verdict for any Spotify entity (playlist, track, artist, curator). It returns:

JSON

{
  "botted": true,
  "metadata": {
    "bottedPlaylistIds": ["1a2b3c...", "4d5e6f..."],
    "bottedPlaylistCount": 2,
    "indicators": { ... },         // For playlists
    "fraudHistory": { ... },       // For playlists
    "adminOverride": { ... }       // For playlists
  }
}

Response Fields

• botted: true or false — whether the entity is currently flagged
• metadata: Contextual info:
  • bottedPlaylistIds: Only for artists/tracks/curators
  • bottedPlaylistCount: Numeric summary
  • indicators, fraudHistory, adminOverride: Only for playlists

---

Best Practices

• Filter out playlists with qualityScore <= -50 for safety.
• Use playlistSummary.fraud to assess overall placement health for a track or artist.
• Use the bot-status endpoint for quick checks or UI gating.
• Human-reviewed overrides (qualityData.override or adminOverride) should always take precedence.

If you need clarification or support integrating this data into your system, reach out to [email protected].

---

Limitations

While artist.tools provides powerful bot detection, there are important limitations to be aware of:

• Not All-Encompassing: Our detection systems are robust, but not exhaustive. Suspicious behavior may go undetected.

• Limited Data on New Playlists: If we've just ingested a playlist, we may not have enough data to provide an assessment. This is common. Allow up to 7 days for full evaluation.

• Use as a Signal, Not a Verdict: We do not recommend using our detection as your only line of defense. Always compare our findings with your own data sources.

• No Access to Internal DSP Data: We rely solely on publicly available data. Platforms like Spotify may have internal signals (e.g. user-level stream behavior) that we cannot observe or factor into our analysis.

• Deeper Insight Available: For those doing deeper audits, the snapshots[] array (enabled via the includeSnapshots API option) allows you to inspect timeline-level playlist growth and make your own assessments.