API REFERENCE

Get Artist Socials

On this page

GET/api/artists/{id}/socials

Retrieve all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass history to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember.

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/socials' \
  --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 social profiles 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

historyinteger

Number of days of follower snapshots to include per profile as history, newest first. Snapshots are written by every scrape that reports a follower count, one point per social per day (the latest scrape that day wins), so a profile has one point after its first scrape and a second only after a scrape on a later day. Omitted: no history field on the profiles.

Responses

200Social profiles retrieved successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success"

socialsarray<SocialProfile>required

List of social media profiles associated with the artist

Item properties

social_idstring

UUID of the artist's socials account

format: uuid

usernamestring

Username on the platform

profile_urlstring

Direct URL to the profile

avatarstringnullable

URL to the profile avatar image

biostringnullable

Profile biography or description

follower_countintegernullable

Number of followers on this platform

following_countintegernullable

Number of accounts followed on this platform

regionstringnullable

Geographic region of the profile

updated_atstring

ISO timestamp of when the profile was last updated

format: date-time

historyarray<SocialSnapshot>

Follower snapshots for the last history days, newest first. Present only when the history query parameter is passed.

Item properties

captured_atstringrequired

When the scrape that produced this point completed

format: date-time

follower_countintegerrequired

Followers (subscribers on YouTube) at capture time

following_countintegernullable

Accounts followed at capture time; null where the platform does not report it

post_countintegernullable

Lifetime post count at capture time (Instagram, TikTok, YouTube, X); null where the platform does not report it

paginationobjectrequired

Pagination metadata for the response

Properties

total_countinteger

Total number of social profiles available

pageinteger

Current page number

limitinteger

Number of social profiles per page

total_pagesinteger

Total number of pages available

400Bad request - invalid id, page, limit or history

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid credentials

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

403Forbidden - caller does not have access to this artist

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

404Artist not found

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

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 all social media profiles associated with an artist, with the latest follower counts from the most recent scrape. Call this before the Social Posts or Social Scrape endpoints to obtain the social IDs. Pass `history` to also get each profile's follower snapshots, so week-over-week movement is a read instead of something the caller has to remember.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The unique identifier of the artist account to fetch social profiles 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
      }
    },
    {
      "name": "history",
      "in": "query",
      "description": "Number of days of follower snapshots to include per profile as `history`, newest first. Snapshots are written by every scrape that reports a follower count, one point per social per day (the latest scrape that day wins), so a profile has one point after its first scrape and a second only after a scrape on a later day. Omitted: no `history` field on the profiles.",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 90
      },
      "example": 14
    }
  ],
  "responses": {
    "200": {
      "description": "Social profiles retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid `id`, `page`, `limit` or `history`",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - caller does not have access to this artist",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Artist not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsErrorResponse"
          }
        }
      }
    }
  }
}