docs(social): optional posts depth param on both social scrape endpoints#258
Merged
Conversation
Documents the new `posts` parameter (integer, 1-100, default 1) on
POST /api/socials/{id}/scrape (query) and POST /api/artist/socials/scrape
(body field), which controls how many recent posts the Apify run dataset
returns with per-post engagement metrics (X/Twitter tweets incl. viewCount;
YouTube videos and Shorts). Also expands the Scraper Results example with
X and YouTube dataset items alongside the Instagram profile item.
Contract for recoupable/chat#1836; the api implementation follows.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
📝 WalkthroughWalkthroughThis PR updates the OpenAPI docs for artist and social scrape endpoints to add an optional ChangesSocial scrape posts documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
api-reference/openapi/releases.json (1)
2109-2116: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider adding an
examplefor the newpostsproperty.Sibling properties in this schema (e.g.,
artist_account_id) and elsewhere in the spec (e.g.,CreateTaskRequestfields) include anexamplevalue. Adding one here (e.g.,"example": 10) keeps the new field consistent with the rest of the schema and helps consumers/doc renderers show a sample value.✏️ Suggested addition
"posts": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1, + "example": 10, "description": "Maximum number of recent posts to include in each scrape dataset, with per-post engagement metrics. Applies to X/Twitter (tweets with like, retweet, reply, quote, bookmark, and view counts) and YouTube (videos and Shorts with view, like, and comment counts). Other platforms ignore this field. When omitted, each scrape returns the legacy profile snapshot (a single latest item)." }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api-reference/openapi/releases.json` around lines 2109 - 2116, The new posts property in the releases schema is missing an example, unlike nearby fields such as artist_account_id and other request schemas. Update the posts entry in the OpenAPI JSON to include a representative example value consistent with its integer range, so schema consumers and docs renderers show a sample for this field.api-reference/openapi/social.json (1)
1036-1082: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider clarifying that item types don't co-occur in a single run.
The example array now shows an Instagram profile item, a tweet item, and a YouTube video item together. Since each
/api/socials/{id}/scraperun targets a single social profile (one platform), a real response would only ever contain items of one type. Thedatadescription at Line 1035 already states structure "varies depending on the scraper type," which largely mitigates this, but an explicit note (e.g., "a single run returns items of only one of these shapes, shown together here for illustration") would remove any ambiguity for API consumers building parsers against this contract.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@api-reference/openapi/social.json` around lines 1036 - 1082, Clarify the mixed example in the social API schema: the example array in the `social.json` response shows Instagram, tweet, and YouTube item shapes together, but a single `/api/socials/{id}/scrape` run only returns one scraper type. Update the example or its surrounding description so it explicitly states that `data` items are mutually exclusive per run and the different shapes are shown only for illustration, using the existing `data`/`example` schema section as the place to adjust.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@api-reference/openapi/releases.json`:
- Around line 2109-2116: The new posts property in the releases schema is
missing an example, unlike nearby fields such as artist_account_id and other
request schemas. Update the posts entry in the OpenAPI JSON to include a
representative example value consistent with its integer range, so schema
consumers and docs renderers show a sample for this field.
In `@api-reference/openapi/social.json`:
- Around line 1036-1082: Clarify the mixed example in the social API schema: the
example array in the `social.json` response shows Instagram, tweet, and YouTube
item shapes together, but a single `/api/socials/{id}/scrape` run only returns
one scraper type. Update the example or its surrounding description so it
explicitly states that `data` items are mutually exclusive per run and the
different shapes are shown only for illustration, using the existing
`data`/`example` schema section as the place to adjust.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 55c7f842-c4f8-4317-9235-5f547682ace4
📒 Files selected for processing (2)
api-reference/openapi/releases.jsonapi-reference/openapi/social.json
Verified against the api#741 preview: on YouTube the depth applies per content type (up to N videos + N Shorts per dataset); on X/Twitter it returns the account's latest N timeline items including retweets and replies. Documented both so callers size posts accordingly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Collaborator
Author
|
Reconciled against live preview verification of recoupable/api#741 (second commit): YouTube |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 2 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
sweetmantech
commented
Jul 2, 2026
| "/api/artist/socials/scrape": { | ||
| "post": { | ||
| "description": "Trigger scrape jobs for all social profiles linked to an artist. Provide an artist_account_id, and the API will look up the artist's socials and invoke a scraping job for each social profile. Each scrape returns Apify run metadata so you can poll for status and retrieve results.", | ||
| "description": "Trigger scrape jobs for all social profiles linked to an artist. Provide an artist_account_id, and the API will look up the artist's socials and invoke a scraping job for each social profile. Each scrape returns Apify run metadata so you can poll for status and retrieve results. Pass `posts` to include recent posts with engagement metrics in each run's dataset (X/Twitter and YouTube; Instagram profile scrapes always include `latestPosts`).", |
Collaborator
Author
There was a problem hiding this comment.
KISS - keep the descriptions simple.
Suggested change
| "description": "Trigger scrape jobs for all social profiles linked to an artist. Provide an artist_account_id, and the API will look up the artist's socials and invoke a scraping job for each social profile. Each scrape returns Apify run metadata so you can poll for status and retrieve results. Pass `posts` to include recent posts with engagement metrics in each run's dataset (X/Twitter and YouTube; Instagram profile scrapes always include `latestPosts`).", | |
| "description": "Trigger scrape jobs for all social profiles linked to an artist. Returns a runId you can poll for status and retrieve results at [endpoint with hyperlink].", |
Collaborator
Author
There was a problem hiding this comment.
Applied in 68fe330 — simplified to: '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 Apify Scraper Results API.' (kept 'per social profile' since the response is an array, one run per platform).
| "/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 Apify run metadata for polling status and retrieving results via the [Apify 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 Apify run metadata for polling status and retrieving results via the [Apify Scraper Results API](/api-reference/apify/scraper). Pass `posts` to include recent posts with engagement metrics in the run's dataset (X/Twitter and YouTube; Instagram profile scrapes always include `latestPosts`).", |
Collaborator
Author
There was a problem hiding this comment.
KISS
Suggested change
| "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 Apify run metadata for polling status and retrieving results via the [Apify Scraper Results API](/api-reference/apify/scraper). Pass `posts` to include recent posts with engagement metrics in the run's dataset (X/Twitter and YouTube; Instagram profile scrapes always include `latestPosts`).", | |
| "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 [Apify Scraper Results API](/api-reference/apify/scraper).", |
Collaborator
Author
There was a problem hiding this comment.
Applied in 68fe330 — reverted to the terse original ('returns run metadata … via the Apify Scraper Results API'); the posts sentence now lives only on the param description.
| "additionalProperties": true | ||
| }, | ||
| "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type (Instagram Profile, Instagram Comments, etc.)", | ||
| "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type. Instagram profile scrapes return a profile item with a `latestPosts` array; X/Twitter scrapes return one tweet item per post (with engagement metrics including `viewCount`); YouTube scrapes return one video item per post. Use the `posts` parameter on the scrape endpoints to control how many post items are returned.", |
Collaborator
Author
There was a problem hiding this comment.
KISS
Suggested change
| "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type. Instagram profile scrapes return a profile item with a `latestPosts` array; X/Twitter scrapes return one tweet item per post (with engagement metrics including `viewCount`); YouTube scrapes return one video item per post. Use the `posts` parameter on the scrape endpoints to control how many post items are returned.", | |
| "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type.", |
Collaborator
Author
There was a problem hiding this comment.
Applied in 68fe330 — reverted to the simple two-sentence description; the example array still shows the three item shapes.
…ault, move nav - Endpoint + data descriptions reverted to terse originals per review; the posts param description remains the single place carrying platform detail - Removed "default": 1 from both posts schemas (cubic P1): the backend distinguishes omitted (legacy snapshot, YouTube Shorts excluded) from posts=1 (Shorts included), so a schema default would mislead SDK generators; added example: 10 instead - Moved api-reference/artist/socials-scrape into the Social Media tab's Social group next to social/scrape Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
1 issue found across 3 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/social.json">
<violation number="1" location="api-reference/openapi/social.json:1035">
P2: The `ApifyScraperCompletedResponse.data` description was generalized from explicit per-platform shape guidance to a generic sentence, even though the schema remains polymorphic (`items: { type: object, additionalProperties: true }`). While the examples array now includes all three platform types, the normative description is the primary contract consumers rely on for parsing expectations. Consider restoring the per-platform shape semantics in the description alongside the expanded examples.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| "additionalProperties": true | ||
| }, | ||
| "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type (Instagram Profile, Instagram Comments, etc.)", | ||
| "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type.", |
There was a problem hiding this comment.
P2: The ApifyScraperCompletedResponse.data description was generalized from explicit per-platform shape guidance to a generic sentence, even though the schema remains polymorphic (items: { type: object, additionalProperties: true }). While the examples array now includes all three platform types, the normative description is the primary contract consumers rely on for parsing expectations. Consider restoring the per-platform shape semantics in the description alongside the expanded examples.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/social.json, line 1035:
<comment>The `ApifyScraperCompletedResponse.data` description was generalized from explicit per-platform shape guidance to a generic sentence, even though the schema remains polymorphic (`items: { type: object, additionalProperties: true }`). While the examples array now includes all three platform types, the normative description is the primary contract consumers rely on for parsing expectations. Consider restoring the per-platform shape semantics in the description alongside the expanded examples.</comment>
<file context>
@@ -1032,7 +1032,7 @@
"additionalProperties": true
},
- "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type. Instagram profile scrapes return a profile item with a `latestPosts` array; X/Twitter scrapes return one tweet item per post (with engagement metrics including `viewCount`); YouTube scrapes return one video item per post. Use the `posts` parameter on the scrape endpoints to control how many post items are returned.",
+ "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type.",
"example": [
{
</file context>
Suggested change
| "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type.", | |
| "description": "Array of dataset items returned by the scraper. The structure of each item varies depending on the scraper type. Instagram profile scrapes return a profile item with a `latestPosts` array. X/Twitter scrapes return one tweet item per post with engagement metrics including `likeCount`, `retweetCount`, `replyCount`, `quoteCount`, `bookmarkCount`, and `viewCount`. YouTube scrapes return one video item per post with `viewCount`, `likes`, and `commentsCount`. Use the `posts` parameter on the scrape endpoints to control how many post items are returned." |
sweetmantech
commented
Jul 2, 2026
sweetmantech
added a commit
to recoupable/api
that referenced
this pull request
Jul 2, 2026
Adds an optional `posts` parameter (integer, 1-100, default: legacy
single-item snapshot) to POST /api/socials/{id}/scrape (query param) and
POST /api/artist/socials/scrape (body field), threaded through
scrapeProfileUrl/scrapeProfileUrlBatch into the platform actor inputs:
- Twitter (apidojo/twitter-scraper-lite): maxItems = posts ?? 1 — returns
the last N tweets with engagement metrics incl. viewCount (impressions)
- YouTube (streamers/youtube-scraper): maxResults = posts ?? 1 and
maxResultsShorts = posts ?? 0 — a requested depth includes Shorts,
which the legacy snapshot explicitly excluded
- Other platforms accept and ignore the param (Instagram profile scrapes
already bundle latestPosts)
Omitting posts produces the exact same actor inputs as before, so existing
profile-snapshot callers and their Apify cost profile are unchanged.
Implements recoupable/chat#1836; contract documented in recoupable/docs#258.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jul 2, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Contract PR for recoupable/chat#1836 — merge before the
apiimplementation PR (docs → api).POST /api/socials/{id}/scrape: new optionalpostsquery param (integer, 1–100, default 1).POST /api/artist/socials/scrape: new optionalpostsbody field (same shape) onArtistSocialsScrapeRequest.GET /api/apify/runs/{runId}):dataexample now shows an X tweet item (withlikeCount/retweetCount/replyCount/quoteCount/bookmarkCount/viewCount) and a YouTube video item (viewCount/likes/commentsCount) alongside the Instagram profile item, and the description explains the per-platform item shapes.Semantics documented:
postsapplies to X/Twitter and YouTube; other platforms ignore it; omitted → legacy single-item profile snapshot (existing behavior unchanged).Verification
json.load) after the edit; diff is additive (59 insertions / 4 deletions across the two files).maxItems, YouTubemaxResults/maxResultsShorts).🤖 Generated with Claude Code
Summary by cubic
Adds an optional
postsdepth to both social scrape endpoints to include recent posts with engagement metrics. X/Twitter returns the latest N timeline items (incl. retweets/replies) and YouTube returns up to N videos + N Shorts; omit to get the legacy single-item profile snapshot; other platforms ignore it.New Features
POST /api/socials/{id}/scrape:postsquery param (integer 1–100).POST /api/artist/socials/scrape:postsbody field onArtistSocialsScrapeRequest(same shape).Refactors
posts(use example: 10) and tightened endpoint copy; responses now point to the Scraper Results API and the artist scrape notes a runId per social profile.latestPostsplus X and YouTube items; movedapi-reference/artist/socials-scrapeinto the Social group.Written for commit be26ce7. Summary will update on new commits.
Summary by CodeRabbit
postssetting to social scraping APIs (min: 1,max: 100) to return recent post/video data with engagement metrics on supported platforms.runIdresults behavior.postsbehavior (X/Twitter, YouTube, Instagram) and documented legacy snapshot behavior whenpostsis omitted.