diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json
index 92283326..c64d0290 100644
--- a/api-reference/openapi/releases.json
+++ b/api-reference/openapi/releases.json
@@ -925,6 +925,10 @@
     "/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).",
+        "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..e6758e39 100644
--- a/api-reference/openapi/social.json
+++ b/api-reference/openapi/social.json
@@ -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": {
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.