---
title: "List AI sample suggestions"
method: GET
path: "/samples/suggestions"
tags: ["Samples"]
---

# List AI sample suggestions

`GET /samples/suggestions`

Sample requests scored by a sample-request automation running in `mode='suggest'`. Ordered best first: `verdict='qualifies'`, then `preference_score` descending. `summary` counts every verdict for the chosen `status` so you can say e.g. '42 qualify, 10 don't, 5 lack data'. Each item's `reasons` explains the verdict rule by rule. Approve with `POST /samples/suggestions/approve`, dismiss with `.../dismiss`.

## Query parameters

- `automation_id` integer, nullable — Only this automation's suggestions.
- `verdict` 'qualifies' | 'does_not_qualify' | 'insufficient_data', nullable
- `status` 'suggested' | 'approved' | 'dismissed' | 'expired' | 'failed' — `suggested` = still awaiting your decision.
- `page` integer
- `page_size` integer

## Response `200`

Successful Response

- SuggestionListResponse
  - `data` SuggestionItem[], required
    - `suggestion_id` integer, required
    - `automation_id` integer, required
    - `application_id` string, required — TikTok sample application id.
    - `creator_id` string, required
    - `creator_username` string, nullable
    - `product_id` string, required
    - `verdict` 'qualifies' | 'does_not_qualify' | 'insufficient_data', required
    - `qualified_by` 'numbers' | 'video', nullable
    - `preference_score` number, nullable — 0-1, higher ranks first among qualifying creators.
    - `reasons` SuggestionReason[]
      - `rule` string, required — The criterion evaluated, e.g. `video_pace allowed [fast]`.
      - `kind` 'hard' | 'preference' | 'numbers', required
      - `passed` boolean, nullable — Null when it could not be evaluated.
      - `detail` string
    - `scored_at` string, nullable — ISO-8601 UTC.
    - `status` 'suggested' | 'approved' | 'dismissed' | 'expired' | 'failed', required
  - `summary` SuggestionSummary, required
    - `qualifies` integer
    - `does_not_qualify` integer
    - `insufficient_data` integer
  - `pagination` PublicApiCorePaginationPaginationMeta, required — Pagination metadata returned in responses.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer, required

## Other responses

- `422` — Validation Error

## Changes

> 28 revisions in range; 1 not diffed.

- **2026-09-30** `67663b32ec24` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/samples/suggestions/get.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/11512e6b7f67?raw)