---
title: "List proactive post suggestions"
method: GET
path: "/api/v1/suggestions"
tags: ["Analytics"]
---

# List proactive post suggestions

`GET /api/v1/suggestions`

## Request

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

Returns proactive post suggestions (evidence-based weekly drafts written in each account's learned voice) for the caller's workspace. Filterable by account_id and status (pending|scheduled|dismissed, default pending). Each item includes the rationale tying the draft back to the feedback loop. Requires a Pro plan or higher; lower tiers get 403 feature_not_available.

## Query parameters

- `account_id` integer
- `status` 'pending' | 'scheduled' | 'dismissed'
- `limit` integer
- `offset` integer

## Response `200`

Suggestions fetched successfully

- object
  - `suggestions` object[]
    - `id` string
    - `social_account_id` integer
    - `platform` string
    - `account` object
      - `id` integer
      - `username` string, nullable
      - `platform` string
    - `caption` string
    - `rationale` string, nullable
    - `period_key` string, nullable
    - `status` 'pending' | 'scheduled' | 'dismissed'
    - `created_at` string
  - `total` integer: Exact number of matching suggestions across all pages.
  - `limit` integer
  - `offset` integer
  - `has_more` boolean: True when more suggestions exist after this page.
  - `next_offset` integer, nullable

## Other responses

- `400`: Validation error
- `401`: Invalid or missing API key
- `403`: Request is authenticated but not allowed
- `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)