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.