Skip to content

docs(social): credit pricing (5 + posts) + auth on scrape endpoints #259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 2 commits into from
Jul 2, 2026
+114 −1
Merged

docs(social): credit pricing (5 + posts) + auth on scrape endpoints #259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
36dd137
docs(social): credit pricing on both scrape endpoints (5 + posts)
sweetmantech Jul 2, 2026
9b57882
docs(credits): bill social scrape on the shared credits page, not per…
sweetmantech Jul 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 68 additions & 0 deletions api-reference/openapi/releases.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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"
}
}
}
}
}
}
Expand Down Expand Up @@ -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": {
Expand Down
44 changes: 44 additions & 0 deletions api-reference/openapi/social.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -583,6 +583,16 @@
}
}
}
},
"402": {
"description": "Insufficient credits — the body includes a `checkoutUrl` to top up.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SocialInsufficientCreditsResponse"
}
}
}
}
}
}
Expand Down Expand Up @@ -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": {
Expand Down
3 changes: 2 additions & 1 deletion credits.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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). |

@cubic-dev-ai cubic-dev-ai Bot Jul 2, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The "Cost per endpoint" table at the bottom of the page omits the two social scrape endpoints now that they're billed. All other billed families (research variants, image generate, chat) have entries there — social scrape should too for consistency.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At credits.mdx, line 17:

<comment>The "Cost per endpoint" table at the bottom of the page omits the two social scrape endpoints now that they're billed. All other billed families (research variants, image generate, chat) have entries there — social scrape should too for consistency.</comment>

<file context>
@@ -14,7 +14,8 @@ Some Recoup endpoints are billed in **credits** — primarily endpoints that hit
 | **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. |
 
</file context>

| **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.

Expand Down