Skip to content

docs(social): optional posts depth param on both social scrape endpoints #258

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 5 commits into from
Jul 2, 2026
Merged

docs(social): optional posts depth param on both social scrape endpoints #258

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b720585
docs(social): add optional posts depth param to both scrape endpoints
sweetmantech Jul 2, 2026
c82213b
docs(social): reconcile posts semantics with live behavior
sweetmantech Jul 2, 2026
68fe330
docs(social): address review — KISS descriptions, drop misleading def…
sweetmantech Jul 2, 2026
be26ce7
Update api-reference/openapi/releases.json
sweetmantech Jul 2, 2026
639e32a
Update api-reference/openapi/social.json
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
9 changes: 8 additions & 1 deletion api-reference/openapi/releases.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. 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,
Expand Down Expand Up @@ -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,
"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)."
}
}
},
Expand Down
54 changes: 51 additions & 3 deletions api-reference/openapi/social.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 run metadata for polling status and retrieving results via the [Scraper Results API](/api-reference/apify/scraper).",
"parameters": [
{
"name": "id",
Expand All @@ -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. 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).",
Comment thread
cubic-dev-ai[bot] marked this conversation as resolved.
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"example": 10
}
],
"responses": {
Expand Down Expand Up @@ -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.",

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

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

"example": [
{
"id": "123456789",
Expand All @@ -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"
}
]
}
Expand Down
4 changes: 2 additions & 2 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
},
Expand Down Expand Up @@ -213,7 +212,8 @@
{
"group": "Social",
"pages": [
"api-reference/social/scrape"
"api-reference/social/scrape",
"api-reference/artist/socials-scrape"
]
},
{
Expand Down