Get Artist Socials

Retrieve all socials associated with an artist. This endpoint should be called before using the Social Posts Endpoint to obtain the necessary social IDs.

Endpoint

GET https://api.recoupable.com/api/artist/socials

Parameters

Name	Type	Required	Description
artist_account_id	string	Yes	The unique identifier of the artist account to fetch profile data for

Request Examples

cURL

curl -X GET "https://api.recoupable.com/api/artist/socials?artist_account_id=YOUR_ARTIST_ACCOUNT_ID" \
  -H "Content-Type: application/json"
  # -H "Authorization: Bearer YOUR_API_KEY" # Coming soon

Response Format

The API returns JSON responses. Here's an example success response:

{
  "status": "success",
  "socials": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "social_id": "123e4567-e89b-12d3-a456-426614174005",
      "username": "@artistname",
      "profile_url": "https://twitter.com/artistname",
      "avatar": "https://example.com/avatar.jpg",
      "bio": "Official account of Artist Name",
      "follower_count": 50000,
      "following_count": 1000,
      "region": "US",
      "updated_at": "2024-03-27T12:00:00Z"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174002",
      "social_id": "123e4567-e89b-12d3-a456-426614174006",
      "username": "artistname",
      "profile_url": "https://instagram.com/artistname",
      "avatar": "https://example.com/avatar2.jpg",
      "bio": "🎨 Artist | Creator | Innovator",
      "follower_count": 100000,
      "following_count": 500,
      "region": "US",
      "updated_at": "2024-03-27T14:30:00Z"
    }
  ],
  "pagination": {
    "total_count": 2,
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}

Response Properties

Response Object

Property	Type	Description
status	string	Status of the request ("success" or "error")
socials	array	List of social media profiles
socials[].id	string	UUID of the artist's `account_socials` record
socials[].social_id	string	UUID of the artist's `socials` record
socials[].username	string	Username on the platform
socials[].profile_url	string	Direct URL to the profile
socials[].avatar	string \| null	URL to the profile avatar image
socials[].bio	string \| null	Profile biography or description
socials[].follower_count	number \| null	Number of followers on this platform
socials[].following_count	number \| null	Number of accounts followed on this platform
socials[].region	string \| null	Geographic region of the profile
socials[].updated_at	string	ISO timestamp of when the profile was last updated
pagination	object	Pagination metadata for the response
pagination.total_count	number	Total number of social profiles available
pagination.page	number	Current page number
pagination.limit	number	Number of social profiles per page
pagination.total_pages	number	Total number of pages available

Workflow Guide

This endpoint can be used in conjunction with other endpoints for a comprehensive workflow:

Call this endpoint to get an overview of an artist's social media presence
Use the social_id values from the socials array to work with the Social Posts endpoint
Use the artist_account_id to call the Artist Segments endpoint

Example workflow:

// Step 1: Get artist's social profiles
const socialsResponse = await getArtistSocials(
  "123e4567-e89b-12d3-a456-426614174000"
);
 
// Step 2: Use a social ID to get posts for a specific social profile
const socialId = socialsResponse.socials[0].social_id;
const postsResponse = await getSocialPosts(socialId);
 
// Step 3: Get artist's segments
const segmentsResponse = await getArtistSegments(
  "123e4567-e89b-12d3-a456-426614174000"
);
 
// Step 4: Get fans for a specific segment
const segmentId = segmentsResponse.segments[0].segment_id;
const fansResponse = await getSegmentFans(segmentId);