Replies Endpoint - Response Shape Migration
The GET /v1/posts/:id/replies response now returns a consistent comment shape across every network under a new `data` key. The old per-network `replies` key still works and is deprecated.
GET /v1/posts/{id}/replies used to return a different response shape per social network. Nested
replies made that untenable, so the endpoint now returns one consistent comment shape for every
network under a new data key.
Nothing has broken. The old replies key still returns exactly what it returned before, per
network, and will keep doing so until the sunset date announced below. New integrations should read
data; existing integrations should migrate when convenient.
What changed
The response now carries both keys:
{
"success": true,
"data": [ /* consistent across every network - read this */ ],
"replies": [ /* or { "comments": [...] } - the old per-network shape, deprecated */ ]
}data is the same for every network:
| field | type | notes |
|---|---|---|
id | string | Platform comment ID or URN |
author | string | Username, display name, or platform URN |
author_name | string or null | Human-readable name. On LinkedIn, only resolved when you pass resolve_author_names=true (see below) |
author_username | string, optional | Handle or vanity name, when the network provides one |
author_avatar_url | string, optional | Profile picture URL, when the network provides one. May expire |
author_profile_url | string, optional | Public profile URL, when it can be derived |
text | string | Comment content |
created_at | string or null | ISO timestamp, null when the platform does not report one |
like_count | number, optional | Present when the platform reports it |
replies | array, optional | Nested replies. Only present when you pass include_replies=true |
platform_specific | object, optional | The raw platform payload |
Nested replies (include_replies=true) appear only in data. The deprecated replies key never
carries them.
Author names on LinkedIn
LinkedIn identifies commenters by URN (urn:li:person:...) and returns no name alongside it. Pass
resolve_author_names=true and Outstand resolves each commenter into author_name (plus
author_username, author_avatar_url and author_profile_url where LinkedIn provides them).
author always stays the URN, so nothing you read today changes.
- Resolution is best effort. Some commenters cannot be resolved - for example members who limit
their off-LinkedIn visibility. Those come back with
author_name: nulland the URN inauthor. This is expected, not an outage. - LinkedIn does not allow member profile data to be stored. You may cache a resolved name, headline or photo for at most 24 hours; re-fetch after that rather than persisting it.
- Every other network already returns a readable author and ignores the parameter.
Per-network migration
Four networks had a shape that differed from the new one. If you integrate against any of these, these are the fields to remap.
Facebook and Instagram
Both returned an object envelope rather than an array.
// Deprecated `replies` key
{ "comments": [ { "id": "...", "text": "...", "timestamp": "...", "from": { "id": "...", "name": "..." }, "like_count": 5 } ] }deprecated replies | new data |
|---|---|
replies.comments[] | data[] (a plain array, no envelope) |
text | text |
timestamp | created_at |
from (Facebook: object with id and name) | author (the name); the full object stays in platform_specific.from |
username (Instagram) | author; also in platform_specific.username |
like_count | like_count |
replies (Instagram: raw Graph edge, always present) | replies in data, only with include_replies=true |
Bluesky
An array in both, but several fields were renamed. Note the replies field changed meaning: in
the deprecated key it is a reply count; in data it is the array of nested replies.
deprecated replies | new data |
|---|---|
likes | like_count |
replies (a number - the reply count) | platform_specific.replyCount |
reposts | platform_specific.repostCount |
author_display_name | platform_specific.author.displayName |
author_avatar | platform_specific.author.avatar |
id, author, text, created_at | unchanged |
Vimeo
The deprecated key returns Vimeo's raw comment objects.
deprecated replies | new data |
|---|---|
uri | id |
createdOn | created_at |
user.name | author |
text | text |
| the whole raw object | platform_specific |
Every other network
X, Threads and LinkedIn already returned the new shape. For those, replies and data match
except that only data carries the author_name, author_username, author_avatar_url and
author_profile_url fields, so you can switch keys with no other changes.
Deprecation and sunset
Responses from this endpoint carry a Deprecation: true header and a Link header pointing at this
page. The header describes the replies key, not the endpoint itself - the endpoint is not going
anywhere.
The replies key will be removed in a future release. Until then it is frozen: it will not gain
fields, and it will not change shape again.
If you are unsure whether your integration reads replies, search your code for .replies on this
endpoint's response, and for .comments if you integrate Facebook or Instagram.