Get Artist Segments

Retrieve all segments associated with an artist. This endpoint should be called before using the Segment Fans Endpoint to obtain the necessary segment IDs.

Endpoint

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

Parameters

Name	Type	Required	Description
artist_account_id	string	Yes	The unique identifier of the artist account to fetch segments 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/artist/segments?artist_account_id=YOUR_ARTIST_ACCOUNT_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",
  "segments": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "artist_account_id": "123e4567-e89b-12d3-a456-426614174001",
      "segment_id": "123e4567-e89b-12d3-a456-426614174002",
      "updated_at": "2024-03-06T15:33:27Z",
      "segment_name": "Twitter Followers",
      "artist_name": "John Doe"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174003",
      "artist_account_id": "123e4567-e89b-12d3-a456-426614174001",
      "segment_id": "123e4567-e89b-12d3-a456-426614174004",
      "updated_at": "2024-03-06T12:22:15Z",
      "segment_name": "Instagram Followers",
      "artist_name": "John Doe"
    }
  ],
  "pagination": {
    "total_count": 5,
    "page": 1,
    "limit": 20,
    "total_pages": 1
  }
}

Response Properties

Response Object

Property	Type	Description
status	string	Status of the request ("success" or "error")
segments	array	List of segment objects associated with the artist
segments[].id	string	UUID of the `artist_segments` record
segments[].artist_account_id	string	UUID of the artist's `accounts` record
segments[].segment_id	string	UUID of the `segments` record
segments[].updated_at	string	ISO timestamp of when the segment data was last updated
segments[].segment_name	string	Name of the segment (e.g., "Twitter Followers")
segments[].artist_name	string	Name of the artist
pagination	object	Pagination metadata for the response
pagination.total_count	number	Total number of segments available
pagination.page	number	Current page number
pagination.limit	number	Number of segments per page
pagination.total_pages	number	Total number of pages available

Workflow Guide

This endpoint should be called before using the Segment Fans endpoint. The workflow is as follows:

Call the Artist Segments endpoint to retrieve segment IDs for an artist
Use the obtained segment_id values to call the 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);