API REFERENCE

Get Artist Posts

On this page

GET/api/artists/{id}/posts

Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (views, likes, comments, reposts) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/artists/YOUR_ID/posts' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

idstringrequired

The unique identifier of the artist account to fetch posts for

Query parameters

pageinteger

The page number to retrieve (default: 1)

Default: 1

limitinteger

The number of records per page (default: 20, max: 100)

Default: 20

Responses

200Artist posts retrieved successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success"

postsarray<ArtistPost>required

List of posts from the artist across all social platforms

Item properties

idstring

Unique identifier for the post

format: uuid

post_urlstring

Direct URL to the post on the social platform

updated_atstring

ISO timestamp of when the post was published on the platform

format: date-time

viewsintegernullable

View or play count at the last scrape. YouTube viewCount, TikTok playCount, X viewCount. Null on Instagram, LinkedIn, Threads and Facebook.

likesintegernullable

Like count at the last scrape. Instagram likesCount, TikTok diggCount, YouTube likes, X likeCount, LinkedIn likes. Null on Threads and Facebook.

commentsintegernullable

Comment count at the last scrape. Instagram commentsCount, TikTok commentCount, YouTube commentsCount, X replyCount, LinkedIn comments. Null on Threads and Facebook.

repostsintegernullable

Share, repost or retweet count at the last scrape. TikTok shareCount, X retweetCount, LinkedIn shares. Null on Instagram, YouTube, Threads and Facebook.

paginationobjectrequired

Pagination metadata for the response

Properties

total_countinteger

Total number of posts available

pageinteger

Current page number

limitinteger

Number of posts per page

total_pagesinteger

Total number of pages available

400Bad request - invalid or missing id path parameter format

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid credentials

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

403Forbidden - caller does not have access to this artist

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

404Artist not found

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

500Internal server error

application/json

statusstring · enumrequired

Status of the request

Values: "error"

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download social.json

View operation source

json

{
  "description": "Retrieve all social media posts from an artist across all platforms. This endpoint aggregates posts from all connected social media profiles for the specified artist, newest first. Engagement counts (`views`, `likes`, `comments`, `reposts`) are the values captured by the most recent scrape of that profile; they are null on platforms that do not report them and on posts stored before engagement capture. Supports pagination for large post collections.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The unique identifier of the artist account to fetch posts 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 posts retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistPostsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid or missing `id` path parameter format",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistPostsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistPostsErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - caller does not have access to this artist",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistPostsErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Artist not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistPostsErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistPostsErrorResponse"
          }
        }
      }
    }
  }
}