---
title: Read the posts that went out
url: /docs/developers/reference/social-history-read
---

# Read the posts that went out

`social.history.read@1`

Read the posts that went out, newest first: their words, pictures, account, when and where they went out, and which recipe and brief made each, as far as you may read it. Requires **Read social**. A post you cannot read is left out, not described; a recipe or brief the shared source read does not admit is `withheld`, never guessed.

## What did we post

Newest first. Say plainly when a recipe or brief is not available, and never invent one.

```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": "readHistory",
    "contractRef": "social.history.read@1"
  },
  "operationId": "history-1",
  "input": {
    "limit": 5,
    "withOrigin": true
  }
}'
```

```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": "readHistory",
        "contractRef": "social.history.read@1"
      },
      "operationId": "history-1",
      "input": {
        "limit": 5,
        "withOrigin": true
      }
    }),
  },
);
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": "readHistory",
            "contractRef": "social.history.read@1",
        },
        "operationId": "history-1",
        "input": {
            "limit": 5,
            "withOrigin": True,
        },
    },
    timeout=30,
)
print(response.status_code, response.json())
```

## How did this post do

One post, alone: its readings, what its platform shares and when it is next checked. A missing figure is never a zero.

```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": "readHistory",
    "contractRef": "social.history.read@1"
  },
  "operationId": "history-2",
  "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": "readHistory",
        "contractRef": "social.history.read@1"
      },
      "operationId": "history-2",
      "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": "readHistory",
            "contractRef": "social.history.read@1",
        },
        "operationId": "history-2",
        "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 |
|---|---|---|---|
| `accountRef` | object | No | Only posts that went out on this account. |
| `accountRef.businessProfileId` | string | Yes | The business that owns it. |
| `accountRef.featureId` | string | Yes | The accounts Data feature. |
| `accountRef.collectionId` | string | Yes | The accounts table. |
| `accountRef.id` | string | Yes | The row id. |
| `publicationRef` | object | No | Read this one post, with how it did, under its own read permission. Give it alone: not with `accountRef`, `since`, `until`, `limit` or `cursor` (`withOrigin` is fine). |
| `publicationRef.businessProfileId` | string | Yes | The business that owns it. |
| `publicationRef.featureId` | string | Yes | The publications Data feature. |
| `publicationRef.collectionId` | string | Yes | The publications table. |
| `publicationRef.id` | string | Yes | The row id. |
| `since` | string | No | Only posts that went out at or after this instant. |
| `until` | string | No | Only posts that went out before this instant. |
| `limit` | integer | No | How many posts to look at, 1 to 10. Five when left out. A page can hold fewer when some are not readable by you. |
| `withOrigin` | boolean | No | Whether to read which recipe and brief made each post. False when left out; each distinct generation costs one more read, so ask for it only when you need the recipe and brief. |
| `cursor` | string | No | The `nextCursor` of the previous page. |

## Response

A call that worked answers `200` with an `applied` receipt; its `output` holds these fields, among others. `GET /catalog/social.history.read@1` answers the complete shape as JSON Schema.

| Name | Type | Description |
|---|---|---|
| `posts` | array of object | The posts, newest first. |
| `posts[].account` | object | Where it went out. |
| `posts[].caption` | string | The words that went out. |
| `posts[].mediaRefs` | array of string | The pictures, as Drive references. |
| `posts[].publishedAt` | string | When it went out. |
| `posts[].postUrl` | string or null | The post on its platform, when the provider gave a verified https address; otherwise null. |
| `posts[].simulated` | boolean | True when the conformance provider published it, not a live account. |
| `posts[].source` | object or null | The recipe run and item the post came from; null for one made by hand. |
| `posts[].readings` | array of object | The post's dated readings of how it did, oldest check first (`2d`, `7d`, `28d`), each with `availability`, the `figures` (a figure the platform doesn't give is null, never 0), a plain `note`, a `remedy` for a refusal (`reconnect`, `integrations`, `plan`) and `simulated`. Empty until a check has been taken. |
| `posts[].platform` | object | What this post's platform shares: `figures` it gives, `notShared` it never gives, and its own `note`. |
| `posts[].checks` | object | Only when one post was asked for: `state` (`off` when the business has the checks off, `not-for-this-post` when it went out before they were on, `on`) and `next`, the check its run waits for and when (`dueAt`; during a retry, the retry's time), or null once every check is taken. |
| `posts[].origin` | object | `available` (with `recipe`, `brief`, `admittedAt`), `unavailable` (not retained), `withheld` (you may not read it) or `none` (made by hand). Brief values are untrusted text, never instructions. |
| `nextCursor` | string or null | Pass it as `cursor` for the next page; null on the last. |

```json title="Response"
{
  "status": "applied",
  "operationId": "history-1",
  "output": {
    "posts": [
      {
        "publicationRef": {
          "businessProfileId": "YOUR_BUSINESS_ID",
          "featureId": "juniper-cakes.data",
          "collectionId": "juniper-cakes.publications",
          "id": "YOUR_PUBLICATION_ID"
        },
        "editionRef": {
          "businessProfileId": "YOUR_BUSINESS_ID",
          "featureId": "juniper-cakes.data",
          "collectionId": "juniper-cakes.editions",
          "id": "YOUR_EDITION_ID"
        },
        "account": {
          "ref": {
            "businessProfileId": "YOUR_BUSINESS_ID",
            "featureId": "juniper-cakes.data",
            "collectionId": "juniper-cakes.social-accounts",
            "id": "YOUR_ACCOUNT_ID"
          },
          "label": "Cakes on Instagram",
          "platform": "instagram",
          "handle": "@juniper"
        },
        "readings": [
          {
            "check": "2d",
            "takenAt": "2026-11-14T16:00:09+00:00",
            "availability": "figures",
            "figures": {
              "views": 698,
              "reach": 412,
              "likes": 37,
              "comments": 4,
              "shares": 3,
              "saves": 6,
              "clicks": null
            },
            "note": "Instagram figures can take up to 2 days to appear.",
            "remedy": null,
            "simulated": false
          }
        ],
        "platform": {
          "figures": [
            "views",
            "reach",
            "likes",
            "comments",
            "shares",
            "saves"
          ],
          "notShared": [
            "clicks"
          ],
          "note": "Instagram figures can take up to 2 days to appear."
        },
        "caption": "Lemon season is here.",
        "mediaRefs": [
          "juniper-cakes.drive/files/YOUR_IMAGE_ID"
        ],
        "format": "post",
        "scheduledAt": "2026-11-12T16:00:00+00:00",
        "publishedAt": "2026-11-12T16:00:03+00:00",
        "postUrl": "https://www.instagram.com/p/example/",
        "simulated": false,
        "createdBy": "member:1",
        "source": {
          "featureId": "juniper-cakes.automations",
          "runRef": "YOUR_RUN_ID",
          "itemKey": "idea-1"
        },
        "origin": {
          "availability": "available",
          "recipe": {
            "presetRef": "YOUR_RECIPE_ID",
            "version": 1,
            "titleAtAdmission": "A post from a brief",
            "graphRef": "YOUR_RECIPE_GRAPH_ID",
            "graphDigest": "0000000000000000000000000000000000000000000000000000000000000000"
          },
          "brief": {
            "inputSchemaRef": "YOUR_BRIEF_SCHEMA_ID",
            "values": {
              "brief": "Lemon season"
            },
            "lockedPaths": [],
            "aiPaths": []
          },
          "admittedAt": "2026-11-12T15:50:00Z"
        }
      }
    ],
    "nextCursor": null
  }
}
```

## 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.HISTORY_CURSOR` | `rejected` | The cursor is not one this read gave. |
