# Get Artist Socials

Source: https://recoupable.dev/docs/api-reference/artists/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.

## GET /api/artists/{id}/socials

Full OpenAPI specification: https://recoupable.dev/docs/spec/releases.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Releases",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/artists/{id}/socials": {
      "get": {
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ArtistSocialsResponse": {
        "type": "object",
        "required": [
          "status",
          "socials",
          "pagination"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success"
            ],
            "description": "Status of the request"
          },
          "socials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SocialProfile"
            },
            "description": "List of social media profiles associated with the artist"
          },
          "pagination": {
            "$ref": "#/components/schemas/ArtistSocialsPagination",
            "description": "Pagination metadata for the response"
          }
        }
      },
      "ArtistSocialsErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "message": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      },
      "SocialProfile": {
        "type": "object",
        "properties": {
          "social_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the artist's socials account"
          },
          "username": {
            "type": "string",
            "description": "Username on the platform"
          },
          "profile_url": {
            "type": "string",
            "description": "Direct URL to the profile"
          },
          "avatar": {
            "type": "string",
            "nullable": true,
            "description": "URL to the profile avatar image"
          },
          "bio": {
            "type": "string",
            "nullable": true,
            "description": "Profile biography or description"
          },
          "follower_count": {
            "type": "integer",
            "nullable": true,
            "description": "Number of followers on this platform"
          },
          "following_count": {
            "type": "integer",
            "nullable": true,
            "description": "Number of accounts followed on this platform"
          },
          "region": {
            "type": "string",
            "nullable": true,
            "description": "Geographic region of the profile"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp of when the profile was last updated"
          },
          "history": {
            "type": "array",
            "description": "Follower snapshots for the last `history` days, newest first. Present only when the `history` query parameter is passed.",
            "items": {
              "$ref": "#/components/schemas/SocialSnapshot"
            }
          }
        }
      },
      "ArtistSocialsPagination": {
        "type": "object",
        "properties": {
          "total_count": {
            "type": "integer",
            "description": "Total number of social profiles available"
          },
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "limit": {
            "type": "integer",
            "description": "Number of social profiles per page"
          },
          "total_pages": {
            "type": "integer",
            "description": "Total number of pages available"
          }
        }
      },
      "SocialSnapshot": {
        "type": "object",
        "required": [
          "captured_at",
          "follower_count"
        ],
        "properties": {
          "captured_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the scrape that produced this point completed"
          },
          "follower_count": {
            "type": "integer",
            "description": "Followers (subscribers on YouTube) at capture time"
          },
          "following_count": {
            "type": "integer",
            "nullable": true,
            "description": "Accounts followed at capture time; null where the platform does not report it"
          },
          "post_count": {
            "type": "integer",
            "nullable": true,
            "description": "Lifetime post count at capture time (Instagram, TikTok, YouTube, X); null where the platform does not report it"
          }
        }
      }
    }
  }
}
```