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