Get Segment Fans

Retrieve all social profiles from fans within a specific segment. This endpoint should be called after obtaining segment IDs from the Artist Segments Endpoint endpoint.

Endpoint

GET https://api.recoupable.com/api/segment/fans

Parameters

Name	Type	Required	Description
segment_id	string	Yes	The unique identifier of the segment to fetch fans for
page	number	No	The page number to retrieve (default: 1)
limit	number	No	The number of records per page (default: 20, max: 100)

Request Examples

cURL

curl -X GET "https://api.recoupable.com/api/segment/fans?segment_id=YOUR_SEGMENT_ID&page=1&limit=20" \
  -H "Content-Type: application/json"

Response Format

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

{
  "status": "success",
  "fans": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "username": "@superfan",
      "avatar": "https://example.com/avatar1.jpg",
      "profile_url": "https://twitter.com/superfan",
      "segment_id": "123e4567-e89b-12d3-a456-426614174002",
      "segment_name": "Twitter Followers",
      "fan_social_id": "123e4567-e89b-12d3-a456-426614174005",
      "region": "US",
      "bio": "Music lover and digital art collector",
      "follower_count": 1234,
      "following_count": 567,
      "updated_at": "2024-03-06T15:33:27Z"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "username": "artcollector",
      "avatar": "https://example.com/avatar2.jpg",
      "profile_url": "https://instagram.com/artcollector",
      "segment_id": "123e4567-e89b-12d3-a456-426614174002",
      "segment_name": "Twitter Followers",
      "fan_social_id": "123e4567-e89b-12d3-a456-426614174006",
      "region": "UK",
      "bio": "Supporting emerging artists 🎨",
      "follower_count": 5678,
      "following_count": 432,
      "updated_at": "2024-03-06T12:22:15Z"
    }
  ],
  "pagination": {
    "total_count": 156,
    "page": 1,
    "limit": 20,
    "total_pages": 8
  }
}

Response Properties

Response Object

Property	Type	Description
status	string	Status of the request ("success" or "error")
fans	array	List of social profiles from fans in the segment
fans[].id	string	Unique identifier for the `fan_segments` record
fans[].username	string	Username or handle on the platform
fans[].avatar	string	URL to the fan's avatar/profile image
fans[].profile_url	string	Full URL to the fan's profile on the platform
fans[].segment_id	string	UUID of the fan's `segments` record
fans[].segment_name	string	Name of the segment (e.g., "Twitter Followers")
fans[].fan_social_id	string	UUID of the fan's `socials` media profile account
fans[].region	string	Geographic region or location of the fan
fans[].bio	string	Fan's biography or profile description
fans[].follower_count	number	Number of followers the fan has
fans[].following_count	number	Number of accounts the fan is following
fans[].updated_at	string	ISO timestamp of when the fan data was last updated
pagination	object	Pagination metadata for the response
pagination.total_count	number	Total number of records available
pagination.page	number	Current page number
pagination.limit	number	Number of records per page
pagination.total_pages	number	Total number of pages available

Workflow Guide

This endpoint is part of a workflow involving the Artist Segments endpoint:

First, call the Artist Segments Endpoint with an artist_account_id to retrieve available segments
From the response, select the desired segment_id value
Use that segment_id to call this Segment Fans endpoint

Example workflow:

// Step 1: Get all segments for an artist
const segmentsResponse = await getArtistSegments(
  "10fd2b53-3fb8-4d75-bd23-f28520a3c7fc"
);
 
// Step 2: Use a segment ID to get fans for a specific segment
const segmentId = segmentsResponse.segments[0].segment_id;
const fansResponse = await getSegmentFans(segmentId);
 
// Now you have fans specific to that segment
console.log(
  `Fans in segment ${segmentsResponse.segments[0].segment_name}:`,
  fansResponse.fans
);