From b720585ab841a63aabd6e17844f1c482f7402285 Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Thu, 2 Jul 2026 07:38:17 -0500 Subject: [PATCH 1/5] docs(social): add optional posts depth param to both scrape endpoints 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 --- api-reference/openapi/releases.json | 9 ++++- api-reference/openapi/social.json | 54 +++++++++++++++++++++++++++-- 2 files changed, 59 insertions(+), 4 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 9bfe4743..da1df544 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. 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`).", "requestBody": { "description": "Artist to scrape socials for", "required": true, @@ -2106,6 +2106,13 @@ "format": "uuid", "description": "UUID of the artist account to scrape socials for", "example": "1873859c-dd37-4e9a-9bac-80d35a1b2c3d" + }, + "posts": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 1, + "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)." } } }, diff --git a/api-reference/openapi/social.json b/api-reference/openapi/social.json index 27dc115a..38656efc 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 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`).", "parameters": [ { "name": "id", @@ -549,6 +549,18 @@ "type": "string", "format": "uuid" } + }, + { + "name": "posts", + "in": "query", + "description": "Maximum number of recent posts to include in the 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 parameter. When omitted, the scrape returns the legacy profile snapshot (a single latest item).", + "required": false, + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 1 + } } ], "responses": { @@ -1020,7 +1032,7 @@ "type": "object", "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.", "example": [ { "id": "123456789", @@ -1029,7 +1041,43 @@ "biography": "This is a sample biography", "followersCount": 1000, "followsCount": 500, - "profilePicUrl": "https://example.com/profile.jpg" + "profilePicUrl": "https://example.com/profile.jpg", + "latestPosts": [ + { + "shortCode": "AbCdEfGhIjK", + "type": "Video", + "caption": "Example reel caption", + "likesCount": 16, + "commentsCount": 4, + "videoViewCount": 56, + "timestamp": "2026-06-30T00:26:41.000Z" + } + ] + }, + { + "type": "tweet", + "id": "1234567890123456789", + "url": "https://x.com/example_user/status/1234567890123456789", + "text": "Example tweet text", + "createdAt": "Wed Jul 01 17:38:08 +0000 2026", + "likeCount": 7, + "retweetCount": 2, + "replyCount": 1, + "quoteCount": 0, + "bookmarkCount": 1, + "viewCount": 258 + }, + { + "type": "video", + "id": "aBcDeFgHiJk", + "title": "Example Short", + "url": "https://www.youtube.com/watch?v=aBcDeFgHiJk", + "date": "2026-07-01T17:55:00.000Z", + "viewCount": 26, + "likes": 1, + "commentsCount": 0, + "duration": "00:00:45", + "channelUsername": "examplechannel" } ] } From c82213b2f6261f64c36440fe18e4bfa95ce4bfda Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Thu, 2 Jul 2026 08:05:30 -0500 Subject: [PATCH 2/5] docs(social): reconcile posts semantics with live behavior 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 --- api-reference/openapi/releases.json | 2 +- api-reference/openapi/social.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index da1df544..b8898d50 100644 --- a/api-reference/openapi/releases.json +++ b/api-reference/openapi/releases.json @@ -2112,7 +2112,7 @@ "minimum": 1, "maximum": 100, "default": 1, - "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)." + "description": "Maximum number of recent posts to include in each scrape dataset, with per-post engagement metrics. On X/Twitter this returns the account's latest `posts` timeline items — including retweets and replies — each with like, retweet, reply, quote, bookmark, and view counts. On YouTube the depth applies per content type, so each dataset contains up to `posts` videos plus `posts` Shorts, each with view, like, and comment counts. Other platforms ignore this field. When omitted, each scrape returns the legacy profile snapshot (a single latest item)." } } }, diff --git a/api-reference/openapi/social.json b/api-reference/openapi/social.json index 38656efc..210dea0a 100644 --- a/api-reference/openapi/social.json +++ b/api-reference/openapi/social.json @@ -553,7 +553,7 @@ { "name": "posts", "in": "query", - "description": "Maximum number of recent posts to include in the 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 parameter. When omitted, the scrape returns the legacy profile snapshot (a single latest item).", + "description": "Maximum number of recent posts to include in the scrape dataset, with per-post engagement metrics. On X/Twitter this returns the account's latest `posts` timeline items — including retweets and replies — each with like, retweet, reply, quote, bookmark, and view counts. On YouTube the depth applies per content type, so the dataset contains up to `posts` videos plus `posts` Shorts, each with view, like, and comment counts. Other platforms ignore this parameter. When omitted, the scrape returns the legacy profile snapshot (a single latest item).", "required": false, "schema": { "type": "integer", From 68fe330c460756138cb0377e0503cfe54a19cfdc Mon Sep 17 00:00:00 2001 From: Sweets Sweetman Date: Thu, 2 Jul 2026 08:52:44 -0500 Subject: [PATCH 3/5] =?UTF-8?q?docs(social):=20address=20review=20?= =?UTF-8?q?=E2=80=94=20KISS=20descriptions,=20drop=20misleading=20default,?= =?UTF-8?q?=20move=20nav?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- api-reference/openapi/releases.json | 4 ++-- api-reference/openapi/social.json | 10 +++++----- docs.json | 4 ++-- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index b8898d50..993ce0f3 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. 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 per social profile that you can poll for status and results via the [Apify Scraper Results API](/api-reference/apify/scraper).", "requestBody": { "description": "Artist to scrape socials for", "required": true, @@ -2111,7 +2111,7 @@ "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. On X/Twitter this returns the account's latest `posts` timeline items — including retweets and replies — each with like, retweet, reply, quote, bookmark, and view counts. On YouTube the depth applies per content type, so each dataset contains up to `posts` videos plus `posts` Shorts, each with view, like, and comment counts. Other platforms ignore this field. When omitted, each scrape returns the legacy profile snapshot (a single latest item)." } } diff --git a/api-reference/openapi/social.json b/api-reference/openapi/social.json index 210dea0a..d5e3aed1 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 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).", "parameters": [ { "name": "id", @@ -558,9 +558,9 @@ "schema": { "type": "integer", "minimum": 1, - "maximum": 100, - "default": 1 - } + "maximum": 100 + }, + "example": 10 } ], "responses": { @@ -1032,7 +1032,7 @@ "type": "object", "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": [ { "id": "123456789", diff --git a/docs.json b/docs.json index 14aa944d..a5de16b8 100644 --- a/docs.json +++ b/docs.json @@ -45,7 +45,6 @@ "api-reference/artists/unpin", "api-reference/artists/delete", "api-reference/artists/socials", - "api-reference/artist/socials-scrape", "api-reference/artist/profile" ] }, @@ -213,7 +212,8 @@ { "group": "Social", "pages": [ - "api-reference/social/scrape" + "api-reference/social/scrape", + "api-reference/artist/socials-scrape" ] }, { From be26ce7181644da28bd370cbf886922e5628776e Mon Sep 17 00:00:00 2001 From: "sweetman.eth" Date: Thu, 2 Jul 2026 09:53:53 -0500 Subject: [PATCH 4/5] Update api-reference/openapi/releases.json --- api-reference/openapi/releases.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi/releases.json b/api-reference/openapi/releases.json index 993ce0f3..92283326 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 [Apify 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).", "requestBody": { "description": "Artist to scrape socials for", "required": true, From 639e32aa80294343b41c79a966cef994db627ea6 Mon Sep 17 00:00:00 2001 From: "sweetman.eth" Date: Thu, 2 Jul 2026 09:54:03 -0500 Subject: [PATCH 5/5] Update api-reference/openapi/social.json --- api-reference/openapi/social.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-reference/openapi/social.json b/api-reference/openapi/social.json index d5e3aed1..e6a6301e 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 [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 run metadata for polling status and retrieving results via the [Scraper Results API](/api-reference/apify/scraper).", "parameters": [ { "name": "id",