RecoupGet a free auditFree audit

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"
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/artist/socials/scrape' \
  --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"
          }
        }
      }
    }
  }
}