API REFERENCE

Scrape Artist Socials

On this page

POST/api/artist/socials/scrape

Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the Scraper Results API.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/artist/socials/scrape' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "artist_account_id": "1873859c-dd37-4e9a-9bac-80d35a1b2c3d"
}'

Request body required

Artist to scrape socials for

application/json

artist_account_idstringrequired

UUID of the artist account to scrape socials for

format: uuid

postsinteger

Recent-post depth applied to every profile in the batch. Honored on TikTok, YouTube (per content type), X and LinkedIn; ignored on Instagram (always the profile's latest posts, up to 12), Threads and Facebook. Without it TikTok, YouTube and X return a single latest item. Every returned post is stored with its engagement counts; see the per-platform table on Social Scrape. Credits: 5 + posts per profile.

minimum: 1 · maximum: 100

Responses

200Scrape jobs triggered successfully

application/json

runIdstring

Unique identifier for the Apify run

datasetIdstring

Unique identifier for the dataset containing scraped data

errorstringnullable

Error message if the run failed (null if successful)

400Bad request - missing required parameters

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid credentials

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

402Insufficient credits — the body includes a static billingUrl. No Stripe object is created.

application/json

errorstring · enumrequired

Values: "insufficient_credits"

remaining_creditsintegerrequired

required_creditsintegerrequired

billingUrlstringrequired

Static link to the Recoup app, where a human can save a card and buy credits. It is a constant, not a freshly minted Stripe Checkout Session, so a credit-gated endpoint that keeps returning 402 creates nothing. To buy credits programmatically, call POST /api/credits/sessions.

403Forbidden - caller does not have access to this artist

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

Full specification

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

Download releases.json

View operation source

json

{
  "description": "Trigger scrape jobs for all social profiles linked to an artist. Returns a runId per social profile that you can poll for status and results via the [Scraper Results API](/api-reference/apify/scraper).",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "requestBody": {
    "description": "Artist to scrape socials for",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ArtistSocialsScrapeRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Scrape jobs triggered successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsScrapeResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing required parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid credentials",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsErrorResponse"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits — the body includes a static `billingUrl`. No Stripe object is created.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsInsufficientCreditsResponse"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - caller does not have access to this artist",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ArtistSocialsErrorResponse"
          }
        }
      }
    }
  }
}