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

Lookup by URL

On this page
GET/api/research/lookup

Resolve a Spotify artist URL or ID through Recoup Research. Supply spotifyId (22 alphanumeric characters) or a Spotify artist url; a nonempty spotifyId takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an id is included when the artist identifier can be resolved.

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/lookup' \
  --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/research/lookup'

Parameters

Query parameters

urlstring

Spotify artist URL. Required unless spotifyId is provided.

spotifyIdstring

Spotify artist ID. Required unless url is provided.

Responses

200Artist profile matching the platform URL

application/json

statusstring
resultstring
messagestring
artist_infoobject

Full artist record — identity, bio, genres, platform links, and related artists.

Properties for artist_info
namestring
avatarstring
site_urlstring
countrystringnullable

ISO country code.

biostringnullable
genresarray<string>
Item properties for genres

string

linksarray<ResearchLink>
Item properties for links
sourcestring

Platform name, e.g. spotify, apple_music.

external_idstring

Platform-specific ID.

urlstring
isrcstring

ISRC (tracks only).

Additional properties

Additional keys are allowed.

related_artistsarray<ResearchArtistRef>
Item properties for related_artists
idstring

Provider-neutral artist ID.

namestring
avatarstringnullable

Artist image URL.

site_urlstringnullable

Artist page URL.

Additional properties

Additional keys are allowed.

Additional properties

Additional keys are allowed.

idstring

Opaque Recoup research artist ID when resolved. Reuse it in artist research requests; it is separate from the Recoup artist account UUID and Spotify ID.

Additional properties

Additional keys are allowed.

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": "Resolve a Spotify artist URL or ID through Recoup Research. Supply `spotifyId` (22 alphanumeric characters) or a Spotify artist `url`; a nonempty `spotifyId` takes precedence. Apple Music URLs and Recoup account UUIDs are not accepted. Available artist metadata is returned; an `id` is included when the artist identifier can be resolved.\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": "url",
      "in": "query",
      "required": false,
      "description": "Spotify artist URL. Required unless `spotifyId` is provided.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "spotifyId",
      "in": "query",
      "required": false,
      "description": "Spotify artist ID. Required unless `url` is provided.",
      "schema": {
        "type": "string",
        "example": "3TVXtAsR1Inumwj472S9r4",
        "pattern": "^[A-Za-z0-9]{22}$"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Artist profile matching the platform URL",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ResearchLookupResponse"
          }
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}