Read a post's engagers (live)

Written and maintained by The ProspectAPIs team

GET/v1/posts/engagers

GET /v1/posts/engagers is the ProspectAPIs operation getPostEngagers, in the People reads group of the REST API. Read who reacted to or commented on a public post. Fetched fresh at request time, not from a stored cache. $0.012 per live read. Set kind and give one of post_id, share_id or post_url. Billed per call once the reads are live; while they are not yet on sale the call is free (GET /pricing reports people_reads.available). Cost: $0.012 per live read. Send your API key as a Bearer token in the Authorization header.

The quickstart shows this call in context, next to the first requests most integrations make.

Parameters

Parameters of GET /v1/posts/engagers
Name	In	Type	Description
kind required	query	string: reactions, comments	reactions (who reacted) or comments (who commented).
post_id	query	string	The post: the post reference the posts read returns (id), its numeric activity id, or its activity, share or ugcPost URN as the post's address shows it.
share_id	query	string	The post's content id: the share_id the posts read returns, a numeric id, or its share or ugcPost URN as the post's address shows it.
post_url	query	string	The public post URL.
start	query	integer	Reactions only: zero-based offset.
count	query	integer	Results per page, 1 to 50.
cursor	query	string	Comments only: opaque cursor from the previous page.
include_replies	query	boolean	Comments only: true nests every reply under its comment (replies, read in pages, up to 100 a comment, with replies_page: returned, total, has_more; total is null when unknown, and has_more is true when more replies exist than were read). Default false. For comments, page.total counts every comment on the post, replies included, when page.total_includes_replies is true; otherwise it is the top-level count, or null when unknown.

An unknown query parameter is refused with a 400 rather than ignored, so a typo never widens a search you pay for.

Responses

Response codes of GET /v1/posts/engagers
Status	Meaning
200	The post's reactors or commenters and a page cursor, read fresh.
400	The request was invalid (e.g. a bad filter or input); nothing was charged.
401	The API key is missing or invalid.
402	Out of credits. The body carries top_up_url; nothing was charged.
429	Too many requests; retry after the window.
503	This read is temporarily unavailable. Nothing was charged.

Every error answers with the same JSON body, an error string and sometimes a code; the errors page lists each status and when it happens. A per-key 429 carries Retry-After; see rate limits.

200 response fields

The post's reactors or commenters and a page cursor, read fresh. The body is a PeopleReadResult.

Fields of the 200 response
Field	Type	Description
data required	object	The read result. For search, posts, engagers and followers this is { items, page }; for a profile it is the profile object.
coverage required	object	How complete the source was.
coverage.filled	integer
coverage.of	integer

Response headers
Header	Meaning
RateLimit-Limit	Requests this API key may make per minute.
RateLimit-Remaining	Requests left in the current one-minute window.
RateLimit-Reset	Seconds until the current window resets.

Code samples

Each sample sends the same request. Set PROSPECTAPIS_KEY in your environment first. Values come from the spec's examples; replace them with your own.

curl

curl -G https://api.prospectapis.com/v1/posts/engagers \
  -H "Authorization: Bearer $PROSPECTAPIS_KEY" \
  --data-urlencode "kind=reactions"

JavaScript (fetch)

const params = new URLSearchParams({ kind: "reactions" });
const res = await fetch(`https://api.prospectapis.com/v1/posts/engagers?${params}`, {
  headers: { Authorization: `Bearer ${process.env.PROSPECTAPIS_KEY}` },
});
if (!res.ok) throw new Error(`${res.status}: ${(await res.json().catch(() => ({}))).error ?? res.statusText}`);
const data = await res.json();
console.log(data);

Python (requests)

import os, requests

res = requests.get(
    "https://api.prospectapis.com/v1/posts/engagers",
    headers={"Authorization": f"Bearer {os.environ['PROSPECTAPIS_KEY']}"},
    params={"kind": "reactions"},
    timeout=30,
)
res.raise_for_status()
data = res.json()
print(data)

Billing

Billing reserves before it serves: the call holds what it may cost, serves at most what that hold covers, and refunds the rest when the response closes. Any non-2xx answer refunds the whole hold, so a failed call costs nothing. The response reports your balance in X-Credits-Remaining.

Previous operation: Read a person's posts (live). Next operation: Read a post's resharers (live). Every operation, grouped by area, is on the API reference index.

Create a free account to get a key, then run the samples above with your own values.

Was this page helpful?