---
title: "List creators"
method: POST
path: "/creators/list"
tags: ["Creators"]
---

# List creators

`POST /creators/list`

List affiliate creators for your shop with pagination, sorting, and filtering. GMV represents the creator's lifetime revenue for this shop. Data updates approximately every hour.

## Request body

- CreatorsListRequest — POST /creators/list request body.
  - `page` integer
  - `page_size` integer
  - `sort_by` 'shop_gmv' | 'follower_count' | 'shop_video_count' | 'shop_units_sold' | 'video_views' | 'updated_at' | 'created_at', nullable
  - `sort_dir` 'asc' | 'desc'
  - `start_date` string, date, nullable
  - `end_date` string, date, nullable
  - `status` string, nullable
  - `creator_handle` string, nullable
  - `min_shop_gmv` number, nullable
  - `min_overall_gmv` number, nullable
  - `min_videos` integer, nullable
  - `min_followers` integer, nullable
  - `group_id` string, nullable
  - `tags` string[], nullable
  - `product_id` string, nullable

## Response `200`

Successful Response

- CreatorsListPaginatedResponse
  - `data` CreatorListItem[], required
    - `creator_handle` string, nullable
    - `follower_count` integer, nullable — DB: follower_num
    - `status` string, nullable — Display status from rev_status_mapping()
    - `shop_gmv` number, nullable — Lifetime shop-specific GMV. DB: crm_creators.gmv
    - `overall_gmv` number, nullable — Overall GMV from regional creator table. DB: Creator.gmv_num
    - `creator_level` string, nullable — GMV tier L0–L7, using the same thresholds as the dashboard's 'Creators by Level' chart (derived from overall_gmv: L0=$0, L1<$5k, L2<$25k, L3<$60k, L4<$150k, L5<$400k, L6<$1.0M, L7≥$1.0M). Null when overall GMV is unavailable for the creator.
    - `overall_fulfillment_rate` number, nullable — Overall fulfillment rate from regional creator table
    - `shop_units_sold` integer, nullable — DB: item_sold
    - `shop_video_count` integer, nullable — DB: video_num
    - `video_views` integer, nullable — DB: content_video_views
    - `sample_received` integer, nullable — DB: sample_received_num
    - `commission_rate` number, nullable
    - `est_commission` number, nullable — DB: estimate_commission
    - `fulfillment_rate` number, nullable — Shop-specific fulfillment rate from crm_creators
    - `tags` string[], nullable
    - `product_id` string, nullable
    - `product_title` string, nullable
    - `updated_at` string, nullable
    - `created_at` string, nullable
  - `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)