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.

# 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"
        }
      }
    ]
  }
}'
// 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);
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.
{
  "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), 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.