API REFERENCE

Similar Artists

On this page

GET/api/research/similar

Read unweighted related artists. The accepted audience, genre, mood and musicality values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer limit slices the returned list; invalid or non-positive limits are ignored.

Use your Recoup API key (x-api-key) or supported bearer credential. Successful artist and track research reads cost $0.05 (50,000 micro-dollar credits). Recoup manages the data connections. Coverage and rate limits vary; see Research availability.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/research/similar' \
  --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.

API keyx-api-key header

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

artistquery · string

audiencequery · string

genrequery · string

moodquery · string

musicalityquery · string

limitquery · string

idquery · string

cURL for this request

curl --request GET \
  --url 'https://recoup-api.vercel.app/api/research/similar'

Parameters

Query parameters

artiststring

Artist name; Recoup resolves the first provider search match. Required unless id is supplied. Recoup artist UUID resolution is not implemented here.

audiencestring · enum

Audience overlap weight.

Values: "high", "medium", "low"

Default: "medium"

genrestring · enum

Genre similarity weight.

Values: "high", "medium", "low"

Default: "medium"

moodstring · enum

Mood similarity weight.

Values: "high", "medium", "low"

Default: "medium"

musicalitystring · enum

Musicality similarity weight.

Values: "high", "medium", "low"

Default: "medium"

limitstring

Optional raw string; no Recoup default. For similar artists, only a positive integer limits the returned list; for playlists it passes through to the provider.

idstring

Research artist ID returned by search or lookup; treat it as an opaque string. Required unless artist is supplied; takes precedence when both are provided. This is not a Recoup artist/account ID.

Responses

200Unweighted related artists with provider fields; no overlap scores are computed.

application/json

statusstring

artistsarray<ResearchArtistRef>

Item properties

idstring

Provider-neutral artist ID.

namestring

avatarstringnullable

Artist image URL.

site_urlstringnullable

Artist page URL.

Additional properties

Additional keys are allowed.

totalinteger

Only present if the adapter receives a provider total; not guaranteed.

400Validation error

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

401Authentication failed — invalid or missing API key

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

402Insufficient research credits. The response includes a static billingUrl; no checkout session is created.

application/json

errorstring · enumrequired

Values: "insufficient_credits"

remaining_creditsintegerrequired

required_creditsintegerrequired

billingUrlstringrequired

Static link to the Recoup app, where a human can save a card and buy credits. It is a constant, not a freshly minted Stripe Checkout Session, so a credit-gated endpoint that keeps returning 402 creates nothing. To buy credits programmatically, call POST /api/credits/sessions.

403Credential, account or provider permission denied.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

404Artist/track resolution or requested provider data was not found. A failed name search may be reported as 404; retry with an exact provider ID when known.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

429Provider rate or quota limit. The adapter returns an error status but does not forward provider Retry-After headers. Avoid an unbounded retry loop.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

500Missing provider configuration, transport failure or internal error.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

501The configured research data source does not support this endpoint or data shape.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

501 example

{
  "status": "error",
  "error": "Request failed with status 501"
}

502Upstream provider failed.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

504the configured research data connection request timed out.

application/json

statusstring · enumrequired

Values: "error"

errorstringrequired

Human-readable error message describing what went wrong.

Full specification

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

Download research.json

View operation source

json

{
  "description": "Read unweighted related artists. The accepted `audience`, `genre`, `mood` and `musicality` values (high/medium/low) do not currently change the ranking. No similarity score is calculated. A positive integer `limit` slices the returned list; invalid or non-positive limits are ignored.\n\nUse your Recoup API key (`x-api-key`) or supported bearer credential. Successful artist and track research reads cost $0.05 (50,000 micro-dollar credits). Recoup manages the data connections. Coverage and rate limits vary; see [Research availability](/research-availability).",
  "parameters": [
    {
      "name": "artist",
      "in": "query",
      "required": false,
      "description": "Artist name; Recoup resolves the first provider search match. Required unless id is supplied. Recoup artist UUID resolution is not implemented here.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "audience",
      "in": "query",
      "required": false,
      "description": "Audience overlap weight.",
      "schema": {
        "type": "string",
        "enum": [
          "high",
          "medium",
          "low"
        ],
        "default": "medium"
      }
    },
    {
      "name": "genre",
      "in": "query",
      "required": false,
      "description": "Genre similarity weight.",
      "schema": {
        "type": "string",
        "enum": [
          "high",
          "medium",
          "low"
        ],
        "default": "medium"
      }
    },
    {
      "name": "mood",
      "in": "query",
      "required": false,
      "description": "Mood similarity weight.",
      "schema": {
        "type": "string",
        "enum": [
          "high",
          "medium",
          "low"
        ],
        "default": "medium"
      }
    },
    {
      "name": "musicality",
      "in": "query",
      "required": false,
      "description": "Musicality similarity weight.",
      "schema": {
        "type": "string",
        "enum": [
          "high",
          "medium",
          "low"
        ],
        "default": "medium"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string"
      },
      "description": "Optional raw string; no Recoup default. For similar artists, only a positive integer limits the returned list; for playlists it passes through to the provider."
    },
    {
      "name": "id",
      "in": "query",
      "required": false,
      "description": "Research artist ID returned by search or lookup; treat it as an opaque string. Required unless artist is supplied; takes precedence when both are provided. This is not a Recoup artist/account ID.",
      "schema": {
        "type": "string",
        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
        "example": "artist_123"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Unweighted related artists with provider fields; no overlap scores are computed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchSimilarResponse"
          }
        }
      }
    },
    "400": {
      "description": "Validation error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Authentication failed — invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient research credits. The response includes a static billingUrl; no checkout session is created.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchInsufficientCreditsResponse"
          }
        }
      }
    },
    "403": {
      "description": "Credential, account or provider permission denied.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Artist/track resolution or requested provider data was not found. A failed name search may be reported as 404; retry with an exact provider ID when known.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "429": {
      "description": "Provider rate or quota limit. The adapter returns an error status but does not forward provider Retry-After headers. Avoid an unbounded retry loop.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Missing provider configuration, transport failure or internal error.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "501": {
      "$ref": "#/components/responses/ResearchDataSourceUnsupported"
    },
    "502": {
      "description": "Upstream provider failed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    },
    "504": {
      "description": "the configured research data connection request timed out.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchErrorResponse"
          }
        }
      }
    }
  }
}

Get started with Recoup.

Try Our Platform

Build Your Platform

Similar Artists

Authentication

Request

Try it

Parameters

Query parameters

Responses

Full specification