---
title: Read post destinations
url: /docs/developers/reference/social-destinations-read-v3
---

# Read post destinations

`social.destinations.read@3`

Checks selected accounts against one or more post shapes at once, text, picture or video, before anything is written, made or saved. Every shape gets its own answer: the accounts that can take it, and the accounts that cannot, each with the reason in plain words. One account that cannot take one shape never refuses the rest. For a video, each account that can take it comes back with that platform's video limits in plain words, and `not known` for any limit the platform's documentation does not give; a video that is too long, too short, too large or the wrong shape is reported, never trimmed or converted to fit. The platform's own size limit and GrowLocal's file bound are judged separately, so an undocumented platform size is never hidden behind GrowLocal's. This reads local connector limits, each from the platform's own documentation with its source, not a live provider, and grants no asset-use or publication rights. It needs a key with **Read social**.

## Check a thirty-second Reel

Check an Instagram account against a 30-second 9:16 mp4 as a Reel, before any video is made.

```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": "readShapeDestinations",
    "contractRef": "social.destinations.read@3"
  },
  "operationId": "check-reel-destinations-1",
  "input": {
    "accountRefs": [
      {
        "businessProfileId": "YOUR_BUSINESS_ID",
        "featureId": "juniper-cakes.social",
        "collectionId": "juniper-cakes.accounts",
        "id": "YOUR_ACCOUNT_ID"
      }
    ],
    "format": "reel",
    "shapes": [
      {
        "key": "thirty-second-reel",
        "media": {
          "kind": "video",
          "count": 1,
          "mimeTypes": [
            "video/mp4"
          ],
          "minDurationMs": 30000,
          "maxDurationMs": 30000,
          "aspect": "9:16"
        }
      }
    ]
  }
}'
```

```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": "readShapeDestinations",
        "contractRef": "social.destinations.read@3"
      },
      "operationId": "check-reel-destinations-1",
      "input": {
        "accountRefs": [
          {
            "businessProfileId": "YOUR_BUSINESS_ID",
            "featureId": "juniper-cakes.social",
            "collectionId": "juniper-cakes.accounts",
            "id": "YOUR_ACCOUNT_ID"
          }
        ],
        "format": "reel",
        "shapes": [
          {
            "key": "thirty-second-reel",
            "media": {
              "kind": "video",
              "count": 1,
              "mimeTypes": [
                "video/mp4"
              ],
              "minDurationMs": 30000,
              "maxDurationMs": 30000,
              "aspect": "9:16"
            }
          }
        ]
      }
    }),
  },
);
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": "readShapeDestinations",
            "contractRef": "social.destinations.read@3",
        },
        "operationId": "check-reel-destinations-1",
        "input": {
            "accountRefs": [
                {
                    "businessProfileId": "YOUR_BUSINESS_ID",
                    "featureId": "juniper-cakes.social",
                    "collectionId": "juniper-cakes.accounts",
                    "id": "YOUR_ACCOUNT_ID",
                },
            ],
            "format": "reel",
            "shapes": [
                {
                    "key": "thirty-second-reel",
                    "media": {
                        "kind": "video",
                        "count": 1,
                        "mimeTypes": [
                            "video/mp4",
                        ],
                        "minDurationMs": 30000,
                        "maxDurationMs": 30000,
                        "aspect": "9:16",
                    },
                },
            ],
        },
    },
    timeout=30,
)
print(response.status_code, response.json())
```

## Parameters

What goes in `input`:

| Name | Type | Required | Description |
|---|---|---|---|
| `accountRefs` | array of object | Yes | The accounts to check, 1 to 10; one listed twice is refused. |
| `accountRefs[].businessProfileId` | string | Yes | Your business's id. |
| `accountRefs[].featureId` | string | Yes | The `featureId` of the account's row. |
| `accountRefs[].collectionId` | string | Yes | The `collectionId` of the account's row. |
| `accountRefs[].id` | string | Yes | The account's id. |
| `format` | one of `post`, `story`, `reel` | Yes | The format every shape is checked as: `post`, `reel` or `story`. A reel or a story needs a video; only Facebook and Instagram take them. |
| `shapes` | array of object | Yes | The post shapes to check, 1 to 20. |
| `shapes[].key` | string | Yes | A name for the shape, unique among the shapes; the answer carries it back. |
| `shapes[].media` | any JSON value | Yes | The complete declared post-media shape. |
| `shapes[].media.kind` | one of `none`, `image`, `video` | Yes | `none` for text only, `image` for one to ten images, or `video`. |
| `shapes[].media.count` | integer | Yes | Zero for `none`; otherwise the exact number of attachments, one to ten. A reel or a story takes one video. |
| `shapes[].media.mimeTypes` | array of string | Yes | All distinct possible MIME types, such as `image/png` or `video/mp4`; empty for text only. |
| `shapes[].media.minDurationMs` | integer | No | Video only, optional: the shortest video the recipe can make, in milliseconds. |
| `shapes[].media.maxDurationMs` | integer | No | Video only, optional: the longest video the recipe can make, in milliseconds. Every length from the shortest to the longest must fit the account. |
| `shapes[].media.aspect` | string | No | Video only, optional: the shape the recipe makes as `width:height`, such as `9:16`. |
| `shapes[].media.maxBytes` | integer | No | Video only, optional: the largest the video file can be, in bytes. |

## Response

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

| Name | Type | Description |
|---|---|---|
| `shapes` | array of object | One answer per shape, in the order you asked. |
| `shapes[].key` | string | The shape's key, as sent. |
| `shapes[].destinations` | array of object | The accounts that can take the shape, in the order you asked. |
| `shapes[].destinations[].accountRef` | object | The account. |
| `shapes[].destinations[].platform` | one of `facebook`, `instagram`, `linkedin`, `x`, `tiktok`, `youtube`, `pinterest`, `threads`, `bluesky` | Its platform. |
| `shapes[].destinations[].label` | string | The account's name. |
| `shapes[].destinations[].constraints` | object | What the platform allows. |
| `shapes[].destinations[].video` | object | Only for a video shape: this account's video limits in plain words, and what could not be checked. |
| `shapes[].destinations[].video.lines` | array of object | The limits as `field`, `label` and `text`: the platform's shortest and longest video, shape and file size, and the largest file GrowLocal itself sends. The text is exactly `not known` when the platform's documentation gives no such limit; GrowLocal's own file bound is always known and is checked on its own. |
| `shapes[].destinations[].video.notKnown` | array of string | What the shape states that could not be checked, in plain words: a limit the platform does not give, or one that differs by account (such as TikTok's 3, 5 or 10 minutes). Empty when everything stated was checked. |
| `shapes[].incompatible` | array of object | The accounts that cannot take the shape, in the order you asked, each with its `accountRef`, `platform` and a `reason` in plain words. |
| `videoLimits` | array of object | Only when a shape is a video: each account's declared video limits for the format you asked, as numbers (null is not known), with `sources` saying where each was read and the words it was read from. |
| `videoLimits[].limits.sources` | object | For each limit that is not null, the document, its address, the quoted words and the day it was read. |

```json title="Response"
{
  "status": "applied",
  "operationId": "check-reel-destinations-1",
  "output": {
    "shapes": [
      {
        "key": "thirty-second-reel",
        "destinations": [
          {
            "accountRef": {
              "businessProfileId": "YOUR_BUSINESS_ID",
              "featureId": "juniper-cakes.social",
              "collectionId": "juniper-cakes.accounts",
              "id": "YOUR_ACCOUNT_ID"
            },
            "platform": "instagram",
            "label": "Juniper Cakes",
            "constraints": {
              "captionLimit": 2200,
              "formats": [
                "post",
                "reel",
                "story"
              ],
              "options": [
                "shareToFeed",
                "collaborators"
              ],
              "optionChoices": {},
              "mediaRequired": true,
              "maxMedia": 10,
              "mediaTypes": [
                "image/gif",
                "image/jpeg",
                "image/png",
                "image/webp",
                "video/mp4",
                "video/quicktime",
                "video/webm"
              ]
            },
            "video": {
              "lines": [
                {
                  "field": "minDurationMs",
                  "label": "Shortest video",
                  "text": "3 seconds"
                },
                {
                  "field": "maxDurationMs",
                  "label": "Longest video",
                  "text": "up to 15 minutes"
                },
                {
                  "field": "aspect",
                  "label": "Shape",
                  "text": "from 1:100 to 10:1, 9:16 recommended"
                },
                {
                  "field": "maxBytes",
                  "label": "File size",
                  "text": "up to 300 MB"
                },
                {
                  "field": "connectorMaxBytes",
                  "label": "Largest file GrowLocal sends",
                  "text": "up to 100 MB"
                }
              ],
              "notKnown": []
            }
          }
        ],
        "incompatible": []
      }
    ],
    "videoLimits": [
      {
        "accountRef": {
          "businessProfileId": "YOUR_BUSINESS_ID",
          "featureId": "juniper-cakes.social",
          "collectionId": "juniper-cakes.accounts",
          "id": "YOUR_ACCOUNT_ID"
        },
        "platform": "instagram",
        "format": "reel",
        "limits": {
          "minDurationMs": 3000,
          "maxDurationMs": 900000,
          "sureMaxDurationMs": null,
          "minAspect": "1:100",
          "maxAspect": "10:1",
          "recommendedAspect": "9:16",
          "maxBytes": 300000000,
          "connectorMaxBytes": 104857600,
          "sources": {
            "minDurationMs": {
              "citation": "Instagram Platform, Reel specifications",
              "url": "https://developers.facebook.com/docs/instagram-api/reference/ig-user/media",
              "quote": "Duration: 15 mins maximum, 3 seconds minimum",
              "read": "2026-11-14"
            },
            "maxDurationMs": {
              "citation": "Instagram Platform, Reel specifications",
              "url": "https://developers.facebook.com/docs/instagram-api/reference/ig-user/media",
              "quote": "Duration: 15 mins maximum, 3 seconds minimum",
              "read": "2026-11-14"
            },
            "minAspect": {
              "citation": "Instagram Platform, Reel specifications",
              "url": "https://developers.facebook.com/docs/instagram-api/reference/ig-user/media",
              "quote": "Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16",
              "read": "2026-11-14"
            },
            "maxAspect": {
              "citation": "Instagram Platform, Reel specifications",
              "url": "https://developers.facebook.com/docs/instagram-api/reference/ig-user/media",
              "quote": "Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16",
              "read": "2026-11-14"
            },
            "recommendedAspect": {
              "citation": "Instagram Platform, Reel specifications",
              "url": "https://developers.facebook.com/docs/instagram-api/reference/ig-user/media",
              "quote": "we recommend 9:16 to avoid cropping or blank space",
              "read": "2026-11-14"
            },
            "maxBytes": {
              "citation": "Instagram Platform, Reel specifications",
              "url": "https://developers.facebook.com/docs/instagram-api/reference/ig-user/media",
              "quote": "File size: 300MB maximum",
              "read": "2026-11-14"
            },
            "connectorMaxBytes": {
              "citation": "GrowLocal's publishing connector",
              "url": null,
              "quote": "A file over 100 MiB is refused before anything is sent (integrations/postforme.py, MAX_MEDIA_BYTES).",
              "read": "2026-11-14"
            }
          },
          "note": 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 |
|---|---|---|
| `DATA.ROW_NOT_FOUND` | `rejected` | No such account here for this key. |
| `SOCIAL.ACCOUNT_DUPLICATE` | `rejected` | An account is listed twice. |
| `SOCIAL.SHAPE_DUPLICATE` | `rejected` | Two shapes have the same key. |
| `SOCIAL.MEDIA_DESCRIPTOR_INVALID` | `rejected` | A video's shortest length is longer than its longest. |
