---
title: Read posting times and what holds them
url: /docs/developers/reference/social-placement-context-read
---

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

```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": "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"
  }
}'
```

```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": "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);
```

```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": "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. |

```json title="Response"
{
  "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](../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.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. |
