Social
Comments on the posts your ads run as (on Meta, Facebook and Instagram posts): read, reply, hide, unhide and delete, as far as the platform allows.
Get a post with comments
The Facebook Page post or Instagram media a thread's comments are under, as people see it above them: its Page, text, picture (a video's still), link card (link, headline, description, call to action type) and the reaction (Instagram: like), comment and share counts. platform is facebook or instagram, id the postId of its comments. Read from Meta when asked and never stored; a part Meta doesn't give, or every part when Meta doesn't answer, is null. Only posts whose comments Pluto reads; others are 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The {platform}'s ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
callToAction- The call to action's type, e.g.
LEARN_MORE. comments- Comments, as Meta counts them.
createdTime- Posted.
description- The link card's description.
headline- The link card's headline.
id- Meta's post (
{page}_{post}) or media ID. imageUrl- The picture, or a video's still (https, Meta's CDN).
instagramUsername- The Instagram account linked to the Page.
linkUrl- Where the link card goes.
message- The post's text (Instagram: caption).
pageId- The Page.
pageName- The Page's name.
pagePictureUrl- The Page's profile picture (https, Meta's CDN).
pending- Your new comments on the post that Meta hasn't confirmed yet, and the latest that failed today.
pending[].actorpending[].actor.id- Person, API key or agent client.
pending[].actor.kind- Actor kind.One of
person,api_key,agent,system pending[].actor.name- Name at the time.
pending[].createdAt- Asked.
pending[].error- Why it failed, for the person or agent.
pending[].finishedAt- Meta confirmed or refused.
pending[].id- Action.
pending[].jobId- The job that sends it to Meta (
GET /jobs/{id}). pending[].kind- What was asked.One of
reply,hide,unhide,delete,like,unlike,comment pending[].message- The reply's text (replies).
pending[].statuspendinguntil Meta confirms.One ofpending,succeeded,failedpermalinkUrl- Meta's link to the post.
platform- Platform.One of
facebook,instagram reactions- Facebook: reactions; Instagram: likes (null when the account hides them).
shares- Shares (Facebook).
video- A video.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/social/posts/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/0e184a05-aa74-4050-983b-55b53f3970f8" \
-H "Authorization: Bearer $PLUTO_KEY"Comment on a post
Comments on the post as your brand, at the top of its comments: on Facebook as the Page that owns the post, on Instagram as the account the ad runs as. platform is facebook or instagram, id the postId of its comments; only posts whose comments Pluto reads. 202 with the queued action; once Meta confirms (usually within seconds) the comment appears on the post attributed to you. Up to 2,200 characters.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The {platform}'s ID. |
Idempotency-Key | string | Optional | The command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
message- The comment, 1-2,200 characters.
Response
actionaction.actoraction.actor.id- Person, API key or agent client.
action.actor.kind- Actor kind.One of
person,api_key,agent,system action.actor.name- Name at the time.
action.createdAt- Asked.
action.error- Why it failed, for the person or agent.
action.finishedAt- Meta confirmed or refused.
action.id- Action.
action.jobId- The job that sends it to Meta (
GET /jobs/{id}). action.kind- What was asked.One of
reply,hide,unhide,delete,like,unlike,comment action.message- The reply's text (replies).
action.statuspendinguntil Meta confirms.One ofpending,succeeded,failed
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 409The connection lacks the permissions (
reason: meta_permissions,missingPermissions). - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/social/posts/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/0e184a05-aa74-4050-983b-55b53f3970f8/comments" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Idempotency-Key: e62ed6d5-2fe2-444e-9170-e2f55af666e7" \
-H "Content-Type: application/json" \
-d '{
"message": "Can we try the 4x5 cut for Instagram feed before we publish?"
}'Mark a post read
Marks the post's comments read for you, as opening its thread on the Comments page does. A post's thread is unread for each person until they open it, and again once someone other than the brand comments after that; your read is your own and changes nothing for anyone else. platform is the comments' platform (facebook, instagram, or another platform's), id their postId. through is the time of the newest comment you had in front of you, so a comment that arrived meanwhile stays unread; without it, everything on the post now. A read never goes back. Needs a credential that acts for a person. Only posts whose comments Pluto reads; others are 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The {platform}'s ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
through- The newest comment you saw (its
createdTime); default: the post's newest now.
Response
platform- The post's platform, as its comments name it.
postId- The post's ID there.
readThrough- The newest comment you've read on it; null when you haven't, or marked it unread.
unread- It has a comment by someone other than the brand that you haven't read.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/social/posts/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/0e184a05-aa74-4050-983b-55b53f3970f8/read" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"through": "2026-09-25T11:00:00Z"
}'Set a post's state
Sets the post's place in your team's inbox, as Meta Business Suite's folders: followUp marks it to come back to (or clears the mark), done moves it out of the inbox (or back). A post in Done comes back to the inbox when someone other than your brand comments after it was moved there. Both are the team's: everyone in the workspace sees them, unlike the read marks, which are each person's. What the body leaves out stays as it is. Only posts whose comments Pluto reads; others are 404.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The {platform}'s ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Request body
donetrue: move to Done;false: back to the inbox.followUptrue: follow up;false: clear it.
Response
done- In Done: moved there, with no comment by someone other than your brand since.
doneAt- When it was last moved to Done.
followUp- Your team follows it up.
followUpAt- When it was marked.
platform- The post's platform, as its comments name it.
postId- The post's ID there.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/social/posts/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/0e184a05-aa74-4050-983b-55b53f3970f8/state" \
-H "Authorization: Bearer $PLUTO_KEY" \
-H "Content-Type: application/json" \
-d '{
"done": true,
"followUp": true
}'Mark a post unread
Marks the post's comments unread for you, as Meta Business Suite's "Mark as unread": it stays unread until you open its thread again. A post with no comment by someone other than the brand has nothing to be unread. Yours alone, like /read. Needs a credential that acts for a person.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
platform | string | Required | |
id | string | Required | The {platform}'s ID. |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
platform- The post's platform, as its comments name it.
postId- The post's ID there.
readThrough- The newest comment you've read on it; null when you haven't, or marked it unread.
unread- It has a comment by someone other than the brand that you haven't read.
Errors
- 400The request is malformed.
- 401No valid credential.
- 403The credential lacks the permission, or belongs to another workspace.
- 404Not found in this workspace.
- 429Too many requests from this credential. Wait
Retry-Afterseconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/social/posts/59a4cf9d-a07f-4bfd-9d81-e8712666cabf/0e184a05-aa74-4050-983b-55b53f3970f8/unread" \
-H "Authorization: Bearer $PLUTO_KEY"