From 36dd137d3ae8bb7eaf5adc91127997ce0a2f685a Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Thu, 2 Jul 2026 12:51:58 -0500 Subject: [PATCH 1/2] docs(social): credit pricing on both scrape endpoints (5 + posts) Both scrape endpoints now cost 5 credits plus 1 credit per requested post (per profile on the bulk endpoint). Adds the 402 insufficient-credits response (mirrors the research family's schema) to both, and documents auth (security + 401/403) on POST /api/artist/socials/scrape, which gains authentication as part of the same change. Contract for the credit-gate item on recoupable/chat#1836; api PR follows. Co-Authored-By: Claude Fable 5 --- api-reference/openapi/releases.json | 70 ++++++++++++++++++++++++++++- api-reference/openapi/social.json | 46 ++++++++++++++++++- 2 files changed, 114 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 92283326..25364ce1 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -924,7 +924,11 @@ }, "/api/artist/socials/scrape": { "post": { - "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).", + "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). Costs 5 credits plus 1 credit per post requested via `posts`, for each social profile scraped.", + "security": [ + { "apiKeyAuth": [] }, + { "bearerAuth": [] } + ], "requestBody": { "description": "Artist to scrape socials for", "required": true, @@ -956,6 +960,36 @@ } } } + }, + "401": { + "description": "Unauthorized - missing or invalid credentials", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ArtistSocialsErrorResponse" + } + } + } + }, + "402": { + "description": "Insufficient credits — the body includes a `checkoutUrl` to top up.", + "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" + } + } + } } } } @@ -2046,6 +2080,40 @@ } } }, + "ArtistSocialsInsufficientCreditsResponse": { + "type": "object", + "description": "Returned (402) when the account lacks credits for the scrapes and auto-recharge did not cover the call.", + "properties": { + "error": { + "type": "string", + "enum": [ + "insufficient_credits" + ] + }, + "remaining_credits": { + "type": "integer", + "example": 0 + }, + "required_credits": { + "type": "integer", + "example": 100 + }, + "checkoutUrl": { + "type": "string", + "description": "Stripe checkout link to top up credits." + }, + "declineReason": { + "type": "string", + "description": "Card decline reason when auto-recharge was attempted and failed." + } + }, + "required": [ + "error", + "remaining_credits", + "required_credits", + "checkoutUrl" + ] + }, "ArtistSocialsPagination": { "type": "object", "properties": { diff --git a/api-reference/openapi/social.json b/api-reference/openapi/social.json index e6a6301e..a80c5142 100644 --- a/api-reference/openapi/social.json +++ b/api-reference/openapi/social.json @@ -538,7 +538,7 @@ }, "/api/socials/{id}/scrape": { "post": { - "description": "Trigger a social profile scraping job for a given social profile. Use the [Get Artist Socials](/api-reference/artists/socials) endpoint first to retrieve the social profile id values. The response returns run metadata for polling status and retrieving results via the [Scraper Results API](/api-reference/apify/scraper).", + "description": "Trigger a social profile scraping job for a given social profile. Use the [Get Artist Socials](/api-reference/artists/socials) endpoint first to retrieve the social profile id values. The response returns run metadata for polling status and retrieving results via the [Scraper Results API](/api-reference/apify/scraper). Costs 5 credits, plus 1 credit per post requested via `posts`.", "parameters": [ { "name": "id", @@ -583,6 +583,16 @@ } } } + }, + "402": { + "description": "Insufficient credits — the body includes a `checkoutUrl` to top up.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SocialInsufficientCreditsResponse" + } + } + } } } } @@ -1549,6 +1559,40 @@ } } }, + "SocialInsufficientCreditsResponse": { + "type": "object", + "description": "Returned (402) when the account lacks credits for the scrape and auto-recharge did not cover the call.", + "properties": { + "error": { + "type": "string", + "enum": [ + "insufficient_credits" + ] + }, + "remaining_credits": { + "type": "integer", + "example": 0 + }, + "required_credits": { + "type": "integer", + "example": 25 + }, + "checkoutUrl": { + "type": "string", + "description": "Stripe checkout link to top up credits." + }, + "declineReason": { + "type": "string", + "description": "Card decline reason when auto-recharge was attempted and failed." + } + }, + "required": [ + "error", + "remaining_credits", + "required_credits", + "checkoutUrl" + ] + }, "SocialPost": { "type": "object", "properties": { From 9b578823d824d346d4929f73faaf452ffc397b63 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Thu, 2 Jul 2026 13:13:43 -0500 Subject: [PATCH 2/2] docs(credits): bill social scrape on the shared credits page, not per-endpoint Per review direction: no sibling endpoint states its credit cost in its reference description, so the price moves to credits.mdx's What's-billed table (social scrape leaves the free row). The OpenAPI diff keeps only what the endpoints now actually emit: 402 insufficient-credits responses (research-family precedent) and auth (security + 401/403) on the bulk endpoint. Co-Authored-By: Claude Fable 5 --- api-reference/openapi/releases.json | 2 +- api-reference/openapi/social.json | 2 +- credits.mdx | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 25364ce1..c64d0290 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -924,7 +924,7 @@ }, "/api/artist/socials/scrape": { "post": { - "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). Costs 5 credits plus 1 credit per post requested via `posts`, for each social profile scraped.", + "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": [] } diff --git a/api-reference/openapi/social.json b/api-reference/openapi/social.json index a80c5142..e6758e39 100644 --- a/api-reference/openapi/social.json +++ b/api-reference/openapi/social.json @@ -538,7 +538,7 @@ }, "/api/socials/{id}/scrape": { "post": { - "description": "Trigger a social profile scraping job for a given social profile. Use the [Get Artist Socials](/api-reference/artists/socials) endpoint first to retrieve the social profile id values. The response returns run metadata for polling status and retrieving results via the [Scraper Results API](/api-reference/apify/scraper). Costs 5 credits, plus 1 credit per post requested via `posts`.", + "description": "Trigger a social profile scraping job for a given social profile. Use the [Get Artist Socials](/api-reference/artists/socials) endpoint first to retrieve the social profile id values. The response returns run metadata for polling status and retrieving results via the [Scraper Results API](/api-reference/apify/scraper).", "parameters": [ { "name": "id", diff --git a/credits.mdx b/credits.mdx index d1d0a5f0..9aa69c11 100644 --- a/credits.mdx +++ b/credits.mdx @@ -14,7 +14,8 @@ Some Recoup endpoints are billed in **credits** — primarily endpoints that hit | **Research** ([`/api/research/*`](/api-reference/research/search)) | Yes | Each successful call deducts credits. Costs vary by endpoint and parameters (e.g. [`enrich`](/api-reference/research/enrich) charges by processor tier; [`extract`](/api-reference/research/extract) charges by URL count). | | **Content generation** ([`/api/image/generate`](/api-reference/image/generation)) | Yes | Image generation is priced per call. | | **AI Chat — streaming** ([`POST /api/chat`](/api-reference/chat/workflow)) | Yes | Variable cost based on model token usage, with a per-request minimum. | -| **Everything else** | Free at the API layer | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [social integrations](/api-reference/social/scrape), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. | +| **Social scrape** ([`/api/socials/{id}/scrape`](/api-reference/social/scrape), [`/api/artist/socials/scrape`](/api-reference/artist/socials-scrape)) | Yes | 5 credits, plus 1 credit per post requested via `posts` — per social profile scraped. | +| **Everything else** | Free at the API layer | [Artist CRUD](/api-reference/artists/list), [sandboxes](/api-reference/sandboxes/list), [sessions](/api-reference/sessions/get), [scheduled tasks](/api-reference/tasks/get), [account/org management](/api-reference/accounts/id), [agent signup](/api-reference/agents/signup), [Spotify proxies](/api-reference/spotify/search), etc. Subscription gating may still apply. | Failed calls (4xx / 5xx) do **not** deduct credits. Deduction happens only after the upstream call succeeds.