# Get artist fans

Source: https://docs.recoupable.dev/api-reference/fans/get

Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today).

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

Full OpenAPI specification: https://docs.recoupable.dev/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://docs.recoupable.dev/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}/fans": {
      "get": {
        "operationId": "getArtistsByIdFans",
        "description": "Retrieve the social profiles of an artist's fans: the accounts that commented on the artist's scraped posts (Instagram today). Every Instagram scrape is followed by one batched profile run over the new commenters, which fills `avatar`, `bio`, `follower_count` and `following_count` on each fan; `region` is null unless the platform reports one. Supports pagination for large fan lists.\n\n`last_comment_at` is the timestamp of the latest stored comment linked to that fan relationship, when the comment's author matches the returned fan. Missing or mismatched comment evidence returns `null`; it does not mean the fan has never commented. Profile refresh time and other engagement timestamps are not substituted. This is stored evidence, not a live scrape or exhaustive interaction history, and older relationship links are not guaranteed backfilled. Existing ordering, pagination and duplicate fan rows across relationships are unchanged.\n\nThe caller must be authenticated and have access to the artist. This field supports a report's Last heard column; it does not itself return comment bodies. The separate GET /api/comments operation reads saved comment bodies within its authorized linked-post scope, pagination and coverage limits.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The unique identifier of the artist account to fetch fans 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
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Artist fans retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtistFansResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtistFansErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtistFansErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtistFansErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ArtistFansResponse": {
        "type": "object",
        "required": [
          "status",
          "fans",
          "pagination"
        ],
        "example": {
          "status": "success",
          "fans": [
            {
              "id": "fan_fixture_known",
              "username": "example_fan",
              "last_comment_at": "2026-10-01T12:00:00Z"
            },
            {
              "id": "fan_fixture_unknown",
              "username": "example_fan_unknown",
              "last_comment_at": null
            }
          ],
          "pagination": {
            "total_count": 2,
            "page": 1,
            "limit": 20,
            "total_pages": 1
          }
        },
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success"
            ],
            "description": "Status of the request"
          },
          "fans": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ArtistFan"
            },
            "description": "List of social profiles from fans across all platforms"
          },
          "pagination": {
            "$ref": "#/components/schemas/ArtistFansPagination",
            "description": "Pagination metadata for the response"
          }
        }
      },
      "ArtistFansErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "error"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "error": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      },
      "ArtistFan": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the fan's social profile"
          },
          "username": {
            "type": "string",
            "description": "Username or handle on the platform"
          },
          "avatar": {
            "type": "string",
            "description": "URL to the fan's avatar/profile image"
          },
          "profile_url": {
            "type": "string",
            "description": "Full URL to the fan's profile on the platform"
          },
          "region": {
            "type": "string",
            "description": "Geographic region or location of the fan"
          },
          "bio": {
            "type": "string",
            "description": "Fan's biography or profile description"
          },
          "follower_count": {
            "type": "integer",
            "description": "Number of followers the fan has"
          },
          "following_count": {
            "type": "integer",
            "description": "Number of accounts the fan is following"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO timestamp of when the fan data was last updated"
          },
          "last_comment_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Timestamp of the latest stored comment linked to this fan relationship, only when the comment author matches this fan. Null means matching stored comment evidence is unavailable, not that the fan never commented. This is not the profile refresh time, a generic engagement time or a live cross-platform history.",
            "example": "2026-10-01T12:00:00Z"
          }
        }
      },
      "ArtistFansPagination": {
        "type": "object",
        "properties": {
          "total_count": {
            "type": "integer",
            "description": "Total number of records available"
          },
          "page": {
            "type": "integer",
            "description": "Current page number"
          },
          "limit": {
            "type": "integer",
            "description": "Number of records per page"
          },
          "total_pages": {
            "type": "integer",
            "description": "Total number of pages available"
          }
        }
      }
    }
  }
}
```