API REFERENCE

Get Artist Fans

On this page

GET/api/artists/{id}/fans

Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills avatar, bio, follower_count and following_count on each fan; region is null unless the platform reports one. Supports pagination for large fan lists.

Authentication

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

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/artists/YOUR_ID/fans' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

idstringrequired

The unique identifier of the artist account to fetch fans for

Query parameters

pageinteger

The page number to retrieve (default: 1)

Default: 1

limitinteger

The number of records per page (default: 20, max: 100)

Default: 20

Responses

200Artist fans retrieved successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success"

fansarray<ArtistFan>required

List of social profiles from fans across all platforms

Item properties

idstring

Unique identifier for the fan's social profile

usernamestring

Username or handle on the platform

avatarstring

URL to the fan's avatar/profile image

profile_urlstring

Full URL to the fan's profile on the platform

regionstring

Geographic region or location of the fan

biostring

Fan's biography or profile description

follower_countinteger

Number of followers the fan has

following_countinteger

Number of accounts the fan is following

updated_atstring

ISO timestamp of when the fan data was last updated

format: date-time

paginationobjectrequired

Pagination metadata for the response

Properties

total_countinteger

Total number of records available

pageinteger

Current page number

limitinteger

Number of records per page

total_pagesinteger

Total number of pages available

400Bad request - missing required parameters

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid credentials

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

500Internal server error

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

Full specification

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

Download releases.json

View operation source

json

{
  "description": "Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The unique identifier of the artist account to fetch fans for",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "page",
      "in": "query",
      "description": "The page number to retrieve (default: 1)",
      "required": false,
      "schema": {
        "type": "integer",
        "default": 1
      }
    },
    {
      "name": "limit",
      "in": "query",
      "description": "The number of records per page (default: 20, max: 100)",
      "required": false,
      "schema": {
        "type": "integer",
        "default": 20,
        "maximum": 100
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Artist fans retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistFansResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing required parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistFansErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistFansErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistFansErrorResponse"
          }
        }
      }
    }
  }
}