API reference

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/social/posts/{platform}/{id}

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
idpathstringRequiredThe {platform}'s ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

callToActionstring or null
The call to action's type, e.g. LEARN_MORE.
commentsinteger or null
Comments, as Meta counts them.
createdTimestring (date-time) or null
Posted.
descriptionstring or null
The link card's description.
headlinestring or null
The link card's headline.
idstringRequired
Meta's post ({page}_{post}) or media ID.
imageUrlstring or null
The picture, or a video's still (https, Meta's CDN).
instagramUsernamestring or null
The Instagram account linked to the Page.
linkUrlstring or null
Where the link card goes.
messagestring or null
The post's text (Instagram: caption).
pageIdstringRequired
The Page.
pageNamestring or null
The Page's name.
pagePictureUrlstring or null
The Page's profile picture (https, Meta's CDN).
pendingarray of objectsRequired
Your new comments on the post that Meta hasn't confirmed yet, and the latest that failed today.
pending[].actorobjectRequired
pending[].actor.idstring (uuid)Required
Person, API key or agent client.
pending[].actor.kindstringRequired
Actor kind.One of person, api_key, agent, system
pending[].actor.namestringRequired
Name at the time.
pending[].createdAtstring (date-time)Required
Asked.
pending[].errorstring or null
Why it failed, for the person or agent.
pending[].finishedAtstring (date-time) or null
Meta confirmed or refused.
pending[].idstring (uuid)Required
Action.
pending[].jobIdstring (uuid)Required
The job that sends it to Meta (GET /jobs/{id}).
pending[].kindstringRequired
What was asked.One of reply, hide, unhide, delete, like, unlike, comment
pending[].messagestring or null
The reply's text (replies).
pending[].statusstringRequired
pending until Meta confirms.One of pending, succeeded, failed
permalinkUrlstring or null
Meta's link to the post.
platformstringRequired
Platform.One of facebook, instagram
reactionsinteger or null
Facebook: reactions; Instagram: likes (null when the account hides them).
sharesinteger or null
Shares (Facebook).
videobooleanRequired
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-After seconds. 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"
POST/social/posts/{platform}/{id}/comments

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.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
platformpathstringRequired
idpathstringRequiredThe {platform}'s ID.
Idempotency-KeyheaderstringOptionalThe 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-Workspaceheaderstring (uuid)OptionalThe 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

messagestringRequired
The comment, 1-2,200 characters.

Response202 Accepted

actionobjectRequired
action.actorobjectRequired
action.actor.idstring (uuid)Required
Person, API key or agent client.
action.actor.kindstringRequired
Actor kind.One of person, api_key, agent, system
action.actor.namestringRequired
Name at the time.
action.createdAtstring (date-time)Required
Asked.
action.errorstring or null
Why it failed, for the person or agent.
action.finishedAtstring (date-time) or null
Meta confirmed or refused.
action.idstring (uuid)Required
Action.
action.jobIdstring (uuid)Required
The job that sends it to Meta (GET /jobs/{id}).
action.kindstringRequired
What was asked.One of reply, hide, unhide, delete, like, unlike, comment
action.messagestring or null
The reply's text (replies).
action.statusstringRequired
pending until Meta confirms.One of pending, 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; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. 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?"
  }'
POST/social/posts/{platform}/{id}/read

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
idpathstringRequiredThe {platform}'s ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe 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

throughstring (date-time)
The newest comment you saw (its createdTime); default: the post's newest now.

Response200 OK

platformstringRequired
The post's platform, as its comments name it.
postIdstringRequired
The post's ID there.
readThroughstring (date-time) or nullRequired
The newest comment you've read on it; null when you haven't, or marked it unread.
unreadbooleanRequired
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-After seconds. 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"
  }'
POST/social/posts/{platform}/{id}/state

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
idpathstringRequiredThe {platform}'s ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe 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

doneboolean
true: move to Done; false: back to the inbox.
followUpboolean
true: follow up; false: clear it.

Response200 OK

donebooleanRequired
In Done: moved there, with no comment by someone other than your brand since.
doneAtstring (date-time) or nullRequired
When it was last moved to Done.
followUpbooleanRequired
Your team follows it up.
followUpAtstring (date-time) or nullRequired
When it was marked.
platformstringRequired
The post's platform, as its comments name it.
postIdstringRequired
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-After seconds. 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
  }'
POST/social/posts/{platform}/{id}/unread

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.

Permission: read

Parameters

NameTypeRequiredDescription
platformpathstringRequired
idpathstringRequiredThe {platform}'s ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

platformstringRequired
The post's platform, as its comments name it.
postIdstringRequired
The post's ID there.
readThroughstring (date-time) or nullRequired
The newest comment you've read on it; null when you haven't, or marked it unread.
unreadbooleanRequired
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-After seconds. 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"