Read how a post did
social.post-figures.read@1
Read how one delivered post did, or how an account's newest delivered posts did, as the platform reports it through the publishing provider. Requires Read social and the post's own read permission; the connection's own policy then admits or refuses a key. This read posts nothing and costs nothing, and it never shows a missing figure as zero.
How did a delivered post do
Use the publication reference of a post that has gone out. A post that has not gone out is refused. Read it again later for newer totals; do not repeat a waiting answer in a loop.
# A new operationId for each new request; the same one to retry it.
curl https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations \
-H "Authorization: Bearer gl_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target": {
"featureId": "YOUR_FEATURE_ID",
"export": "readPostFigures",
"contractRef": "social.post-figures.read@1"
},
"operationId": "post-figures-1",
"input": {
"publicationRef": {
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.data",
"collectionId": "juniper-cakes.publications",
"id": "YOUR_PUBLICATION_ID"
}
}
}'
// A new operationId for each new request; the same one to retry it.
const response = await fetch(
"https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
{
method: "POST",
headers: {
Authorization: "Bearer gl_YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
"target": {
"featureId": "YOUR_FEATURE_ID",
"export": "readPostFigures",
"contractRef": "social.post-figures.read@1"
},
"operationId": "post-figures-1",
"input": {
"publicationRef": {
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.data",
"collectionId": "juniper-cakes.publications",
"id": "YOUR_PUBLICATION_ID"
}
}
}),
},
);
const receipt = await response.json();
console.log(response.status, receipt);
import requests
# A new operationId for each new request; the same one to retry it.
response = requests.post(
"https://api.growlocal.site/api/v1/profiles/YOUR_BUSINESS_ID/invocations",
headers={"Authorization": "Bearer gl_YOUR_API_KEY"},
json={
"target": {
"featureId": "YOUR_FEATURE_ID",
"export": "readPostFigures",
"contractRef": "social.post-figures.read@1",
},
"operationId": "post-figures-1",
"input": {
"publicationRef": {
"businessProfileId": "YOUR_BUSINESS_ID",
"featureId": "juniper-cakes.data",
"collectionId": "juniper-cakes.publications",
"id": "YOUR_PUBLICATION_ID",
},
},
},
timeout=30,
)
print(response.status_code, response.json())
Parameters
What goes in input:
| Name | Type | Required | Description |
|---|---|---|---|
publicationRef |
object | No | The delivered post to read figures for. Give this or an account. |
publicationRef.businessProfileId |
string | Yes | The business that owns the post. |
publicationRef.featureId |
string | Yes | The post's Data feature. |
publicationRef.collectionId |
string | Yes | The publications table. |
publicationRef.id |
string | Yes | The publication row id. |
accountRef |
object | No | A connected account to read the newest delivered posts of. Only posts that went out through GrowLocal and that you can read are read; posts made on the platform itself never are. Give this or a post. |
accountRef.businessProfileId |
string | Yes | The business that owns the account. |
accountRef.featureId |
string | Yes | The account's Data feature. |
accountRef.collectionId |
string | Yes | The accounts table. |
accountRef.id |
string | Yes | The account row id. |
limit |
integer | No | With an account, how many of its newest delivered posts to look at, 1 to 10. Five when left out. |
Response
A call that worked answers 200 with an applied receipt; its output holds these fields. GET /catalog/social.post-figures.read@1 answers the complete shape as JSON Schema.
| Name | Type | Description |
|---|---|---|
availability |
one of figures, none-given, no-permission, not-yet, not-found, waiting, unreachable |
What happened: figures (at least one figure given), none-given (this platform shares none for the post), no-permission (the account didn't share its figures, or its connection isn't open to this key), not-yet (the post hasn't appeared; Instagram can take two days), not-found (the platform has no such post for the account), waiting (the provider's request limit, or this business's share of it, was reached, so nothing was asked; try again later, not in a loop) or unreachable. |
platform |
string | The platform the account is on. |
simulated |
boolean | True when the answer came from the conformance provider, not a live account. |
takenAt |
string | When the provider was asked. |
note |
string or null | One plain sentence about this platform or account, or null. |
retryAfterSeconds |
integer or null | How long the provider asked to wait after a rate limit, when it said; otherwise null. |
remedy |
one of reconnect, integrations, plan or null |
What to do about a refusal: reconnect (the account didn't share its figures: connect it again and allow results), integrations (this business's connection doesn't allow this kind of caller to read figures: allow it in Integrations) or plan (GrowLocal's plan with the provider, which nothing the business does changes); otherwise null. |
posts |
array of object | Up to 25 delivered posts with their figures; empty when nothing was read or none of the account's posts is readable by you. |
posts[].platformPostRef |
string | The platform's own id for the post. |
posts[].postRef |
string or null | The provider's id for the post when it was made through GrowLocal; null for a post made on the platform itself. |
posts[].url |
string or null | The post on the platform, when the provider gave a verified address; otherwise null. |
posts[].postedAt |
string or null | When the post went out, as the provider reports it. |
posts[].figures |
object | The post's lifetime totals at one moment. A figure the platform does not give is null, never zero. |
posts[].figures.views |
integer or null | Times the post was viewed or shown. |
posts[].figures.reach |
integer or null | Distinct accounts that saw the post. |
posts[].figures.likes |
integer or null | Likes or reactions. |
posts[].figures.comments |
integer or null | Comments or replies. |
posts[].figures.shares |
integer or null | Shares, reposts or retweets. |
posts[].figures.saves |
integer or null | Times the post was saved or bookmarked. |
posts[].figures.clicks |
integer or null | Clicks on the post's link. |
posts[].gaps |
object | A plain reason for each null figure, keyed by figure name. |
{
"status": "applied",
"operationId": "post-figures-1",
"output": {
"availability": "figures",
"platform": "bluesky",
"simulated": false,
"takenAt": "2026-11-14T16:00:00+00:00",
"note": "Bluesky doesn't share views.",
"retryAfterSeconds": null,
"remedy": null,
"posts": [
{
"platformPostRef": "at://did:plc:example/app.bsky.feed.post/3kexample",
"postRef": "YOUR_PROVIDER_POST_ID",
"url": "https://bsky.app/profile/example.bsky.social/post/3kexample",
"postedAt": "2026-11-12T16:00:00+00:00",
"figures": {
"views": null,
"reach": null,
"likes": 9,
"comments": 2,
"shares": 1,
"saves": null,
"clicks": null
},
"gaps": {
"views": "Bluesky doesn't share views.",
"reach": "Bluesky doesn't share reach.",
"saves": "Bluesky doesn't share saves.",
"clicks": "Bluesky doesn't share link clicks."
}
}
]
}
}
Errors
It reads and changes nothing. Besides the answers every request can get (Errors), its receipt can say:
| Status | HTTP | What it means |
|---|---|---|
rejected |
400, or 403 when it's a matter of access | Not done. diagnostics says why: each has a code, a path into what you sent and a message. |
The codes in diagnostics you're most likely to see:
| Code | Status | What it means |
|---|---|---|
SOCIAL.NOT_DELIVERED |
rejected |
The post has not gone out, so it has no figures. |
SOCIAL.FIGURES_TARGET |
rejected |
Neither or both of a post and an account were named. |
SOCIAL.ACCOUNT_NOT_CONNECTED |
rejected |
The named account is not connected in this business, so its provider identity is unknown. |