---
updatedAt: 2025-06-17T21:49:57.000Z
agentTools:
  projectIndex: https://artisttools.readme.io/llms.txt
---

# 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`](https://artisttools.readme.io/reference/get_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 <aaron@artist.tools>.

***

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