---
title: "List sample requests"
method: POST
path: "/samples/list"
tags: ["Samples"]
---

# List sample requests

`POST /samples/list`

Track sample requests from creators in your shop. Shows only sample-related statuses. Data updates approximately every hour.

Each row includes the requesting creator's `bio`, `categories`, and `email` (sourced from the same regional creators table the AI Creator Search API reads), so consumers can score sample requests on brand/niche fit without a second API call. These fields are `null` when the creator has no row in the regional creators table.

## Request body

- SamplesListRequest — POST /samples/list request body.
  - `page` integer
  - `page_size` integer
  - `sort_by` 'updated_at' | 'created_at' | 'gmv', nullable
  - `sort_dir` 'asc' | 'desc'
  - `start_date` string, date, nullable
  - `end_date` string, date, nullable
  - `status` string, nullable
  - `creator_handle` string, nullable
  - `product_id` string, nullable

## Response `200`

Successful Response

- SamplesListPaginatedResponse
  - `data` SampleListItem[], required
    - `creator_handle` string, nullable
    - `product_id` string, nullable
    - `product_title` string, nullable
    - `status` string, nullable — Display status from rev_status_mapping()
    - `gmv` number, nullable
    - `units_sold` integer, nullable
    - `sample_received` integer, nullable
    - `updated_at` string, nullable
    - `bio` string, nullable — Creator bio text. Sourced from the per-region creators table — the same field exposed by the AI Creator Search API. Null when the creator has no regional row.
    - `categories` string[], nullable — Creator categories / niches. Parsed via the same helper the AI Creator Search API uses (handles JSON-array and comma-separated stored values). Null when the creator has no regional row.
    - `email` string, nullable — Creator contact email when known on the regional creators table. Null when the creator has no regional row or no email captured.
  - `currency` string, required
  - `pagination` unknown, required
  - `date_range` DateRange
    - `start_date` string, nullable
    - `end_date` string, nullable
  - `shops_queried` string[], nullable — Shop names included when querying multiple shops (x-shop-id: all or comma-separated).

## Other responses

- `422` — Validation Error

---

[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-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/5eefff009b5b/schema)