---
title: "Get optimal posting times"
method: POST
path: "/api/v1/workspaces/{workspace_id}/scheduling/optimal-times"
tags: ["🕒 Scheduling"]
---

# Get optimal posting times

`POST /api/v1/workspaces/{workspace_id}/scheduling/optimal-times`

Analyse historical performance of the workspace's connected accounts and return the best times to publish, both pooled across accounts (`global`) and per account (`individual`). **A slot is one recommended posting time — a weekday and an hour, in the workspace timezone.** Each account is scored across the week and slots come back ranked best-first, so `slots: 3` means *the three best hours to post*. The slot fields only control how much of that ranking is returned: they never change the analysis, and they do not affect `heatmap_matrix`, which always carries every hour that had signal. Omit `entities` to analyse every account connected to the workspace. Times are always expressed in the workspace timezone (echoed under `meta.timezone`); there is no timezone parameter.

## Path parameters

- `workspace_id` string, required

## Request body

- object
  - `entities` object[] — Accounts to analyse. Omit for every connected account. Each `id` must be an account `_id` from GET /accounts.
    - `id` string, required
    - `type` 'facebook' | 'instagram' | 'linkedin' | 'twitter' | 'tiktok' | 'youtube' | 'pinterest' | 'threads' | 'gmb' | 'tumblr' | 'bluesky' | 'telegram', required
    - `slots` integer — How many recommended times to return for this account, best-first. Overrides `per_account_slots`.
  - `global_slots` integer — How many recommended times to return in the pooled `global` view, best-first.
  - `per_account_slots` integer — How many recommended times to return for each account that does not set its own `slots`.

## Response `200`

Recommendations generated. A workspace with too little history still returns 200 — the accounts are listed under meta.missing_entities.

- object
  - `status` boolean
  - `meta` object
    - `generated_at` string, date-time
    - `timezone` string — The workspace timezone the slots are expressed in
    - `warnings` string[]
    - `missing_entities` string[]
    - `ai_fallback_entities` string[]
  - `global` object, nullable — Pooled view across all analysed accounts. Null when no account had usable data.
    - `top_recommendations` object[]
      - `rank` integer
      - `day` string
      - `date` string
      - `time` string
      - `score` integer
      - `platform_breakdown` object
    - `heatmap_matrix` object — Sparse [hour, day_index, score] triples; day_index 0 = Monday.
      - `data` array[]
        - integer[]
    - `dates_key` string[]
  - `individual` object — Per-account breakdown keyed by account id.

## Other responses

- `401` — Unauthorized
- `403` — Not a member of this workspace
- `422` — Validation error, unknown entities, or no connected accounts
- `429` — Too many requests
- `502` — Post time optimizer unavailable

---

[API](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1.md) · [All operations](https://skmtc.dev/contentstudio/apis/contentstudio-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/contentstudio/contentstudio-api-v1/revisions/ec0c85521883/schema)