---
title: "Suggest the best times to post"
method: GET
path: "/api/v1/slots/suggested"
tags: ["Slots"]
---

# Suggest the best times to post

`GET /api/v1/slots/suggested`

## Request

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

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.

## Query parameters

- `account_ids` string, required: Comma-separated account IDs (at most 25).
- `timezone` string
- `post_type` 'image' | 'video' | 'carousel' | 'story' | 'text'
- `count` integer
- `workspace_id` string
- `include` 'weekly_ratings'

## Response `200`

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

- SuggestedSlotsResponse
  - `timezone` string, 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_label` string, required: Human label for the basis, e.g. "Based on your posts".
  - `slots` object[], required
    - `time` string, date-time, required
    - `local_time` string, required: Wall-clock label in the requested timezone.
    - `basis` 'yours' | 'platform' | 'default', required
    - `reason` string, required: Why this time was picked, in plain language.
    - `stars` integer, required: Rating of this time for the audience, confidence-capped by basis: yours up to 5, platform up to 4, default up to 3.
    - `star_reason` string, required: Tooltip text explaining `stars`, distinct from `reason`.
  - `weekly_ratings` object[]: Only present when include=weekly_ratings is passed. One rating per local hour-of-week (168 total, Sunday 00:00 = index 0) in `timezone`, for the same scoring profile as `slots`.
    - `stars` integer, required
    - `basis` 'yours' | 'platform' | 'default', required
    - `reason` string, required
    - `estimated` boolean, required: True when basis is default: the rating is confidence-capped at 3.

## Other responses

- `400`: Validation error
- `401`: Invalid or missing API key
- `403`: Request is authenticated but not allowed
- `404`: Resource not found
- `429`: Too many requests

---

[API](https://skmtc.dev/poster/apis/posterly-api.md) · [All operations](https://skmtc.dev/poster/apis/posterly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/poster/apis/posterly-api/revisions/60be02a61f95?raw)