---
updatedAt: 2026-08-20T21:36:32.000Z
agentTools:
  projectIndex: https://artisttools.readme.io/llms.txt
---

# Get a track's Press Mentions

Returns normalized pages that link to this track's Spotify URL. Despite the customer-facing name, results may include blogs, directories, profiles, and other web links rather than only editorial press coverage. Lifecycle status is active or lost; isNew is a separate flag calculated from newSince. Filters apply before the exact summary and pagination totals are calculated. Missing or stale SEO data is refreshed automatically with the same stale-data fallback used by Google Rankings.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "artist.tools V2 API",
    "description": "REST API for accessing artist.tools data about Spotify playlists, tracks, artists and curators, as well as miscellaneous utilities. All endpoints are read-only and require an `x-api-key` sent as a request header.",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.artist.tools/v2",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "SEO",
      "description": "Read-only search visibility and press coverage analytics for Spotify entities. Google Rankings and Press Mentions refresh missing or stale stored data automatically; playlist Spotify Rankings use stored observations only."
    }
  ],
  "paths": {
    "/tracks/{id}/press-mentions": {
      "get": {
        "tags": [
          "SEO"
        ],
        "summary": "Get a track's Press Mentions",
        "description": "Returns normalized pages that link to this track's Spotify URL. Despite the customer-facing name, results may include blogs, directories, profiles, and other web links rather than only editorial press coverage. Lifecycle status is active or lost; isNew is a separate flag calculated from newSince. Filters apply before the exact summary and pagination totals are calculated. Missing or stale SEO data is refreshed automatically with the same stale-data fallback used by Google Rankings.",
        "parameters": [
          {
            "$ref": "#/components/parameters/TrackId"
          },
          {
            "$ref": "#/components/parameters/PressMentionQuery"
          },
          {
            "$ref": "#/components/parameters/PressMentionStatus"
          },
          {
            "$ref": "#/components/parameters/PressMentionNewSince"
          },
          {
            "$ref": "#/components/parameters/PressMentionSortBy"
          },
          {
            "$ref": "#/components/parameters/SortDirection"
          },
          {
            "$ref": "#/components/parameters/AnalyticsPage"
          },
          {
            "$ref": "#/components/parameters/AnalyticsLimit"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/PressMentionsResponse"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    },
    "parameters": {
      "TrackId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "1irAliF0T8sLIOPJp6n7rU"
        },
        "description": "Spotify Track ID"
      },
      "AnalyticsPage": {
        "name": "page",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "description": "One-based result page. Invalid values return HTTP 400."
      },
      "AnalyticsLimit": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 25
        },
        "description": "Primary rows per page. Invalid values are rejected rather than clamped."
      },
      "SortDirection": {
        "name": "sortDirection",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        },
        "description": "Sort direction. Google and playlist ranking endpoints default to asc; Press Mentions defaults to desc."
      },
      "PressMentionQuery": {
        "name": "q",
        "in": "query",
        "schema": {
          "type": "string",
          "maxLength": 300
        },
        "description": "Text search across the existing indexed backlink search fields."
      },
      "PressMentionStatus": {
        "name": "status",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "all",
            "new",
            "active",
            "lost"
          ],
          "default": "all"
        },
        "description": "Lifecycle filter. new means active and first observed on or after newSince."
      },
      "PressMentionNewSince": {
        "name": "newSince",
        "in": "query",
        "schema": {
          "oneOf": [
            {
              "type": "string",
              "format": "date"
            },
            {
              "type": "string",
              "format": "date-time"
            }
          ]
        },
        "description": "UTC boundary used for isNew and status=new. Defaults to 30 days before the request."
      },
      "PressMentionSortBy": {
        "name": "sortBy",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "recent",
            "authority"
          ],
          "default": "recent"
        },
        "description": "Primary sort field. recent sorts by when the mention was first observed; authority sorts by source-domain strength. Stable domain and backlink-rank tie-breakers are applied after the selected field."
      }
    },
    "schemas": {
      "SuccessEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "status": {
            "type": "integer",
            "example": 200
          }
        },
        "required": [
          "success",
          "status"
        ]
      },
      "AnalyticsPagination": {
        "type": "object",
        "description": "Pagination metadata for the complete filtered result. Collection responses contain no more than 100 primary rows.",
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 1,
            "description": "Current one-based page."
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "description": "Requested maximum primary rows per page."
          },
          "total": {
            "type": "integer",
            "minimum": 0,
            "description": "Exact number of rows matching all filters before pagination."
          },
          "totalPages": {
            "type": "integer",
            "minimum": 0,
            "description": "Number of pages at the requested limit; zero when total is zero."
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Whether a later page exists."
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Whether an earlier non-empty page exists."
          }
        },
        "required": [
          "page",
          "limit",
          "total",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage"
        ]
      },
      "AnalyticsEntity": {
        "type": "object",
        "description": "The Spotify entity whose analytics are returned.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "artist",
              "track",
              "playlist",
              "curator"
            ],
            "description": "Normalized entity type matching the endpoint resource."
          },
          "spotifyId": {
            "type": "string",
            "description": "Raw Spotify ID supplied in the request path."
          }
        },
        "required": [
          "type",
          "spotifyId"
        ]
      },
      "AnalyticsFreshness": {
        "type": "object",
        "description": "Freshness of the stored entity-level SEO dataset. Google Rankings and Press Mentions attempt an automatic refresh when data is missing or at least seven days old.",
        "properties": {
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC timestamp of the stored dataset used for the response, or null when unavailable."
          },
          "stale": {
            "type": "boolean",
            "description": "True when the returned stored dataset remains at least seven days old, usually because its automatic refresh failed."
          }
        },
        "required": [
          "updatedAt",
          "stale"
        ]
      },
      "PressMentionAuthority": {
        "type": "object",
        "description": "Strength of the source domain using the application's existing source-domain-rank bands.",
        "properties": {
          "score": {
            "type": "number",
            "nullable": true,
            "description": "Source-domain strength score on the application's 0-1000 scale."
          },
          "tier": {
            "type": "string",
            "enum": [
              "unknown",
              "low",
              "medium",
              "high"
            ],
            "description": "unknown when no positive score is available; low below 200; medium from 200 through 699; high from 700."
          }
        },
        "required": [
          "score",
          "tier"
        ]
      },
      "PressMention": {
        "type": "object",
        "description": "One source page linking to the entity's Spotify target. A result is an online mention, not a guarantee of editorial press coverage.",
        "properties": {
          "source": {
            "type": "object",
            "description": "Public information about the page containing the link.",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "nullable": true,
                "description": "Source page URL, or null when unavailable or invalid."
              },
              "domain": {
                "type": "string",
                "nullable": true,
                "description": "Lowercase source domain, or null when unavailable."
              },
              "pageTitle": {
                "type": "string",
                "nullable": true,
                "description": "Observed source page title, or null when unavailable."
              },
              "country": {
                "type": "string",
                "nullable": true,
                "description": "Lowercase source-country value when available; this is not the entity's market."
              },
              "language": {
                "type": "string",
                "nullable": true,
                "description": "Lowercase source-language value when available."
              }
            },
            "required": [
              "url",
              "domain",
              "pageTitle",
              "country",
              "language"
            ]
          },
          "target": {
            "type": "object",
            "description": "Spotify destination linked by the source page.",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "nullable": true,
                "description": "Linked target URL, or null when unavailable or invalid."
              },
              "domain": {
                "type": "string",
                "nullable": true,
                "description": "Lowercase target domain, normally open.spotify.com."
              }
            },
            "required": [
              "url",
              "domain"
            ]
          },
          "anchorText": {
            "type": "string",
            "nullable": true,
            "description": "Visible linked text when available."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "lost"
            ],
            "description": "Whether the link was present at the most recent stored check."
          },
          "isNew": {
            "type": "boolean",
            "description": "True only when the mention is active and firstSeenAt is on or after the request's newSince boundary."
          },
          "firstSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC timestamp when the link was first observed."
          },
          "lastSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC timestamp when the link was most recently observed."
          },
          "lostAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "UTC timestamp when loss was recorded, or null for active links/unknown loss time."
          },
          "dofollow": {
            "type": "boolean",
            "nullable": true,
            "description": "Whether the stored link allows normal search-engine following; null when unavailable."
          },
          "linkType": {
            "type": "string",
            "nullable": true,
            "description": "Lowercase provider classification for the link when available."
          },
          "authority": {
            "$ref": "#/components/schemas/PressMentionAuthority"
          }
        },
        "required": [
          "source",
          "target",
          "anchorText",
          "status",
          "isNew",
          "firstSeenAt",
          "lastSeenAt",
          "lostAt",
          "dofollow",
          "linkType",
          "authority"
        ]
      },
      "PressMentionsData": {
        "type": "object",
        "properties": {
          "entity": {
            "$ref": "#/components/schemas/AnalyticsEntity"
          },
          "freshness": {
            "$ref": "#/components/schemas/AnalyticsFreshness"
          },
          "summary": {
            "type": "object",
            "description": "Totals for the complete filtered result before pagination.",
            "properties": {
              "total": {
                "type": "integer",
                "minimum": 0
              },
              "new": {
                "type": "integer",
                "minimum": 0
              },
              "active": {
                "type": "integer",
                "minimum": 0
              },
              "lost": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "total",
              "new",
              "active",
              "lost"
            ]
          },
          "mentions": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/PressMention"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/AnalyticsPagination"
          }
        },
        "required": [
          "entity",
          "freshness",
          "summary",
          "mentions",
          "pagination"
        ]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          }
        },
        "required": [
          "success",
          "error",
          "status"
        ]
      }
    },
    "responses": {
      "PressMentionsResponse": {
        "description": "Filtered Press Mentions with exact pre-pagination summary totals.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/SuccessEnvelope"
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "press_mentions"
                      ]
                    },
                    "data": {
                      "$ref": "#/components/schemas/PressMentionsData"
                    }
                  },
                  "required": [
                    "type",
                    "data"
                  ]
                }
              ]
            },
            "examples": {
              "newActiveMention": {
                "summary": "New active mention",
                "value": {
                  "success": true,
                  "status": 200,
                  "type": "press_mentions",
                  "data": {
                    "entity": {
                      "type": "playlist",
                      "spotifyId": "2SM6rniZl84fEyMCB5KMQB"
                    },
                    "freshness": {
                      "updatedAt": "2026-08-18T10:00:00.000Z",
                      "stale": false
                    },
                    "summary": {
                      "total": 1,
                      "new": 1,
                      "active": 1,
                      "lost": 0
                    },
                    "mentions": [
                      {
                        "source": {
                          "url": "https://example.com/workout-playlists",
                          "domain": "example.com",
                          "pageTitle": "Workout playlists",
                          "country": "us",
                          "language": "en"
                        },
                        "target": {
                          "url": "https://open.spotify.com/playlist/2SM6rniZl84fEyMCB5KMQB",
                          "domain": "open.spotify.com"
                        },
                        "anchorText": "listen on Spotify",
                        "status": "active",
                        "isNew": true,
                        "firstSeenAt": "2026-08-18T10:00:00.000Z",
                        "lastSeenAt": "2026-08-18T10:00:00.000Z",
                        "lostAt": null,
                        "dofollow": true,
                        "linkType": "anchor",
                        "authority": {
                          "score": 725,
                          "tier": "high"
                        }
                      }
                    ],
                    "pagination": {
                      "page": 1,
                      "limit": 25,
                      "total": 1,
                      "totalPages": 1,
                      "hasNextPage": false,
                      "hasPreviousPage": false
                    }
                  }
                }
              },
              "noMatches": {
                "summary": "Valid filters with no matching mentions",
                "value": {
                  "success": true,
                  "status": 200,
                  "type": "press_mentions",
                  "data": {
                    "entity": {
                      "type": "playlist",
                      "spotifyId": "2SM6rniZl84fEyMCB5KMQB"
                    },
                    "freshness": {
                      "updatedAt": "2026-08-18T10:00:00.000Z",
                      "stale": false
                    },
                    "summary": {
                      "total": 0,
                      "new": 0,
                      "active": 0,
                      "lost": 0
                    },
                    "mentions": [],
                    "pagination": {
                      "page": 1,
                      "limit": 25,
                      "total": 0,
                      "totalPages": 0,
                      "hasNextPage": false,
                      "hasPreviousPage": false
                    }
                  }
                }
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "No stored dataset was available and an automatic SEO refresh failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Client error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}
```