Slots

Suggest the best times to post

Ranks the next 7 days by when the given accounts get the most engagement and returns the best free times, each with a plain-language reason and a 1-5 star rating for the audience (confidence-capped by basis). Slots are at least 30 minutes out, never within 60 minutes of a post already scheduled on these accounts, and spread to one per day when possible. Own engagement data is used only when the key has analytics:read and the account has paid analytics; otherwise the platform-wide pattern (when at least 20 workspaces contribute) or a general default is used, as reported in basis. Every account id must belong to the key's workspace scope; an id outside it returns 404.

get/api/v1/slots/suggested

Request

  • Base URL: https://www.poster.ly
  • URL: https://www.poster.ly/api/v1/slots/suggested
  • Auth: HTTP bearer

Query parameters

account_idsstring required

Comma-separated account IDs (at most 25).

timezonestring

IANA timezone for the slots and labels. Pass it explicitly.

post_type'image' | 'video' | 'carousel' | 'story' | 'text'

Rank by posts of this type when the account has at least 8 of them.

countinteger
workspace_idstring

Workspace the accounts belong to.

include'weekly_ratings'

Pass weekly_ratings to also return the 168-entry (one per local hour-of-week) star rating table, e.g. to rate a time outside the returned slots. Omitted by default to keep the response small.

Response

Suggested slots in time order: the best-scoring free times in the next 7 days, one per day when possible

timezonestring required

The IANA timezone the slots and labels are in.

basis'yours' | 'platform' | 'default' required

yours: ranked from the accounts' own engagement (needs analytics:read and paid analytics). platform: the aggregate pattern for the platform across at least 20 workspaces. default: a general per-platform default.

basis_labelstring required

Human label for the basis, e.g. "Based on your posts".

Example response

{
  "timezone": "Europe/London",
  "basis": "yours",
  "basis_label": "Based on your posts",
  "slots": [
    {
      "time": "2026-10-07T17:00:00.000Z",
      "local_time": "Tue 7 Oct, 6:00 PM",
      "basis": "yours",
      "reason": "Your posts get 2.1x more engagement on Tuesdays around 6pm",
      "stars": 5,
      "star_reason": "Your posts get 2.1x more engagement around this time (34 posts)"
    },
    {
      "time": "2026-10-09T11:00:00.000Z",
      "local_time": "Thu 9 Oct, 12:00 PM",
      "basis": "yours",
      "reason": "A good time for your audience",
      "stars": 3,
      "star_reason": "A good time for your audience"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.