Read posting times and what holds them

social.placement-context.read@1

Read each account's own posting times in a period and which of them are already placed or suggested. Requires Read social. It invents no time, writes nothing and approves, schedules and posts nothing. You name the business time zone; this read does not look it up.

Read two accounts' posting times for a week

Send an instant with its offset for each end of the period. An account with no saved posting times comes back with no slots.

# 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": "readPlacementContext",
    "contractRef": "social.placement-context.read@1"
  },
  "operationId": "placement-context-1",
  "input": {
    "accountRefs": [
      {
        "businessProfileId": "YOUR_BUSINESS_ID",
        "featureId": "juniper-cakes.data",
        "collectionId": "juniper-cakes.social-accounts",
        "id": "YOUR_ACCOUNT_ID"
      }
    ],
    "timeZone": "America/Phoenix",
    "from": "2031-06-02T07:00:00Z",
    "to": "2031-06-09T07:00:00Z"
  }
}'
// 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": "readPlacementContext",
        "contractRef": "social.placement-context.read@1"
      },
      "operationId": "placement-context-1",
      "input": {
        "accountRefs": [
          {
            "businessProfileId": "YOUR_BUSINESS_ID",
            "featureId": "juniper-cakes.data",
            "collectionId": "juniper-cakes.social-accounts",
            "id": "YOUR_ACCOUNT_ID"
          }
        ],
        "timeZone": "America/Phoenix",
        "from": "2031-06-02T07:00:00Z",
        "to": "2031-06-09T07:00:00Z"
      }
    }),
  },
);
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": "readPlacementContext",
            "contractRef": "social.placement-context.read@1",
        },
        "operationId": "placement-context-1",
        "input": {
            "accountRefs": [
                {
                    "businessProfileId": "YOUR_BUSINESS_ID",
                    "featureId": "juniper-cakes.data",
                    "collectionId": "juniper-cakes.social-accounts",
                    "id": "YOUR_ACCOUNT_ID",
                },
            ],
            "timeZone": "America/Phoenix",
            "from": "2031-06-02T07:00:00Z",
            "to": "2031-06-09T07:00:00Z",
        },
    },
    timeout=30,
)
print(response.status_code, response.json())

Parameters

What goes in input:

Name Type Required Description
accountRefs array of object Yes One to ten of the business's accounts, each named once.
accountRefs[].businessProfileId string Yes The business that owns the account.
accountRefs[].featureId string Yes The accounts Data feature.
accountRefs[].collectionId string Yes The accounts table.
accountRefs[].id string Yes The account row id.
timeZone string Yes The business time zone, such as America/Denver. Posting times are wall-clock times in it and carry no zone of their own; read it from the business profile with your own authority.
from string Yes The start of the period, an instant with its offset. Only posting times still ahead are listed.
to string Yes The end of the period (not included): after from and at most 62 days later.

Response

A call that worked answers 200 with an applied receipt; its output holds these fields. GET /catalog/social.placement-context.read@1 answers the complete shape as JSON Schema.

Name Type Description
timeZone string The time zone you named, which the days and wall-clock times are in.
from string The start of the period, in UTC.
to string The end of the period, in UTC.
accounts array of object One entry per asked account, in the order asked.
accounts[].accountRef object The account.
accounts[].accountRef.businessProfileId string The business that owns the account.
accounts[].accountRef.featureId string The accounts Data feature.
accounts[].accountRef.collectionId string The accounts table.
accounts[].accountRef.id string The account row id.
accounts[].slots array of object The posting times the business saved for this account that fall in the period and are still ahead, soonest first. Empty when it has none: no time is invented or borrowed from another account.
accounts[].slots[].at string The moment, in UTC.
accounts[].slots[].date string The day it falls on in the business time zone.
accounts[].slots[].time string Its 24-hour wall-clock time in the business time zone.
accounts[].taken array of object What already holds a moment of this account in the period, soonest first: placements that have not gone out and times suggested for unplaced drafts.
accounts[].taken[].at string The held moment, in UTC.
accounts[].taken[].editionRef object The draft that holds it.
accounts[].taken[].editionRef.businessProfileId string The business that owns the draft.
accounts[].taken[].editionRef.featureId string The editions Data feature.
accounts[].taken[].editionRef.collectionId string The editions table.
accounts[].taken[].editionRef.id string The draft row id.
accounts[].taken[].kind one of placed, proposed placed when the draft is scheduled for it, proposed when it is only suggested.
{
  "status": "applied",
  "operationId": "placement-context-1",
  "output": {
    "timeZone": "America/Phoenix",
    "from": "2031-06-02T07:00:00Z",
    "to": "2031-06-09T07:00:00Z",
    "accounts": [
      {
        "accountRef": {
          "businessProfileId": "YOUR_BUSINESS_ID",
          "featureId": "juniper-cakes.data",
          "collectionId": "juniper-cakes.social-accounts",
          "id": "YOUR_ACCOUNT_ID"
        },
        "slots": [
          {
            "at": "2031-06-02T16:00:00Z",
            "date": "2031-06-02",
            "time": "09:00"
          }
        ],
        "taken": [
          {
            "at": "2031-06-03T16:00:00Z",
            "editionRef": {
              "businessProfileId": "YOUR_BUSINESS_ID",
              "featureId": "juniper-cakes.data",
              "collectionId": "juniper-cakes.editions",
              "id": "YOUR_EDITION_ID"
            },
            "kind": "proposed"
          }
        ]
      }
    ]
  }
}

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.PERIOD_INVALID rejected The period ends before it starts.
SOCIAL.PERIOD_TOO_LONG rejected The period is longer than 62 days.
SOCIAL.TIME_ZONE_UNKNOWN rejected The zone you named is not a real IANA time zone.
SOCIAL.ACCOUNT_DUPLICATE rejected An account is listed twice.
SOCIAL.PLACEMENT_CONTEXT_TOO_LARGE rejected An account holds more placed or suggested posts than one read covers; ask for a shorter period.