---
title: Read how a post did
url: /docs/developers/reference/social-post-figures-read
---

# 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.

```curl tabs
# 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"
    }
  }
}'
```

```javascript tabs
// 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);
```

```python tabs
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. |

```json title="Response"
{
  "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](../errors.md)), 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. |
