---
title: "Xiaohongshu PGY creator search"
method: GET
path: "/v1/xiaohongshu/pgy/creators/search"
tags: ["xiaohongshu"]
---

# Xiaohongshu PGY creator search

`GET /v1/xiaohongshu/pgy/creators/search`

## Request

- Base URL: `https://api.dataxapi.com`
- URL: `https://api.dataxapi.com/v1/xiaohongshu/pgy/creators/search`
- Auth: HTTP bearer

Find Xiaohongshu creators on PGY by search terms, by the filters of PGY's creator square, or both: followers, the price of a sponsored note, estimated CPM, median reads and interactions of everyday and sponsored notes, image or video creators, content category, content feature, persona, where they are, gender, followers' gender and age, industry worked with lately; leaving out the inactive and those losing followers; ordered by followers, price, reads, interactions, shop visits, cost per read, invitations answered, growth, completion and more. Each with creator ID, name, handle, location, content categories and followers, and in the full view prices and medians. A search goes as far as its first 5,000 creators. The creator ID the other PGY endpoints take comes from here.

Price: $0.04 per call.

20 items on a usual page, 20 at most. A cursor is valid for 3600 seconds.

Preview: the returned object may change, announced beforehand.

## Query parameters

- `query` string
- `sort` 'relevance' | 'most_followers' | 'lowest_rate' | 'highest_rate' | 'most_reads' | 'most_engagements' | 'most_impressions' | 'most_sponsored_reads' | 'most_sponsored_engagements' | 'most_sponsored_impressions' | 'most_shop_visits' | 'lowest_read_cost_image' | 'lowest_read_cost_video' | 'highest_reply_rate' | 'fastest_growth' | 'most_active_followers' | 'most_thousand_like_notes' | 'highest_completion_rate'
- `followers_min` integer
- `followers_max` integer
- `rate_min` integer
- `rate_max` integer
- `cpm_min` integer
- `cpm_max` integer
- `median_reads_min` integer
- `median_engagements_min` integer
- `sponsored_median_reads_min` integer
- `type` 'image' | 'video'
- `category` string
- `feature_tag` string
- `persona` string
- `location` string
- `gender` 'female' | 'male'
- `audience_gender` 'female' | 'male'
- `audience_age` 'under_18' | '18_24' | '25_34' | '35_44' | 'over_44'
- `industry` 'beauty' | 'food_drink' | 'mother_baby' | 'electronics' | 'household' | 'fashion' | 'internet' | 'local_services' | 'home_building' | 'auto'
- `exclude` 'low_active' | 'follower_drop' | 'both'
- `cursor` string
- `view` 'compact' | 'standard' | 'full'
- `fields` string[]

## Response `200`

OK

- object: The envelope every capability answers with.
  - `code` 'ok', required
  - `request_id` string, uuid, required
  - `data` object, required
    - `items` object[], required
      - `id` string, nullable: The creator's ID in the marketplace
      - `account_id` string, nullable: ID of the creator's account on the platform, as the platform's account endpoints take it
      - `username` string, nullable: Handle
      - `name` string, nullable: Display name
      - `avatar_url` string, uri, nullable: Avatar (standard view and up)
      - `location` string, nullable: Where the creator is based, in the platform's words (standard view and up)
      - `categories` string[], nullable: Content categories, first level, in the platform's words
      - `subcategories` string[], nullable: Content categories, second level, in the platform's words (standard view and up)
      - `metrics` object, nullable: Creator counts
        - `followers` integer, nullable: Followers
      - `approximate` object[], nullable: Which numbers of this item are approximate or lower bounds; absent when all are exact
        - `field` string, nullable: Path of the field, such as metrics.views
        - `kind` 'approximate' | 'lower_bound' | 'null', nullable: Approximate, or a lower bound
      - `ext` object: The platform's own fields (full view).
        - `rate_image_note` string, nullable: Rate for an image note, in yuan (full view)
        - `rate_video_note` string, nullable: Rate for a video note, in yuan (full view)
        - `rate_lowest` string, nullable: The lowest rate PGY gives (the lower of the image-note and video-note rates), in yuan (full view)
        - `sponsored_notes` integer, nullable: Number of sponsored notes (full view)
        - `median_reads` integer, nullable: Median reads of a note (full view)
        - `median_engagements` integer, nullable: Median interactions of a note (full view)
        - `gender` 'female' | 'male' | 'null', nullable: The creator's gender: female or male; null where the platform says unknown (full view)
        - `feature_tags` string[], nullable: Content feature tags, in the platform's words (such as unboxing, reviews) (full view)
        - `personal_tags` string[], nullable: Persona tags, in the platform's words (such as tech fan, mother) (full view)
        - `industries` string[], nullable: Industries the creator has worked with, in the platform's words (full view)
        - `agency` string, nullable: Name of the agency (MCN) the creator is signed to; null when there is none (full view)
        - `likes_and_favorites` integer, nullable: Likes and saves the creator's notes have received in all, as the profile's likes-and-saves count (full view)
        - `accepts_sponsorship` boolean, nullable: Whether the creator currently takes sponsored work on PGY (full view)
        - `accepts_image_notes` boolean, nullable: Whether the creator takes sponsored image notes (full view)
        - `accepts_video_notes` boolean, nullable: Whether the creator takes sponsored video notes (full view)
        - `sponsored_notes_30d` integer, nullable: Sponsored notes published in the last 30 days (full view)
        - `travel_areas` string[], nullable: The travel areas the creator lists on PGY, in the platform's words (a province, or a province and a city) (full view)
    - `missing` Missing[]
      - `id` string, required
      - `reason` 'not_found' | 'invalid', required
  - `page` Page: Present on capabilities that return lists. A page is asked for with `cursor`; each page is its own call and is charged on its own.
    - `next_cursor` string, nullable, required: Pass as `cursor` for the next page; null when there is none.
    - `cursor_expires_at` string, date-time, nullable, required
    - `has_more` boolean, required
    - `returned` integer, required
  - `warnings` Warning[], required
    - `code` 'items_dropped' | 'items_not_requested' | 'fields_unparsed' | 'text_truncated', required
    - `count` integer: items_dropped, items_not_requested: how many.
    - `item` integer: fields_unparsed, text_truncated: index of the item.
    - `fields` string[]
  - `meta` Meta, required
    - `capability` string, required
    - `result_status` 'complete' | 'partial' | 'empty', required
    - `fetched_at` string, date-time, required
    - `cached` boolean, required: From a shared snapshot.
    - `replayed` boolean, required: The saved result of an earlier call: `request_id` is that call's and nothing was added to the bill.
    - `unavailable` object, required: Fields this result could not carry, each with why.
    - `billing` object, required
      - `amount` string, required: US dollars, as a decimal string.
      - `currency` 'USD', required
      - `balance_after` string, nullable, required
      - `covers_next` unknown
      - `top_up_url` string, uri: With covers_next: where to top up.

## Other responses

- `4XX`: An error. Nothing was charged unless `charged` is null. - `invalid_params` (400, retry: after_fix, charged the endpoint's price where its data source billed the answer): A parameter is invalid - `request_not_served` (400, retry: after_fix): This combination of parameters cannot be served at present - `max_price_exceeded` (400, retry: after_fix): The most this call could cost is above the limit you set - `cursor_invalid` (400, retry: no): The cursor does not exist - `cursor_mismatch` (400, retry: after_fix): The cursor was issued for another endpoint or other parameters - `unauthorized` (401, retry: no): No credential was sent, or it is invalid, disabled or expired - `insufficient_balance` (402, retry: after_fix): The balance is too low - `key_budget_exceeded` (402, retry: after_fix): This key's spending limit does not cover the call - `run_budget_exceeded` (402, retry: no): This run's amount or call limit does not cover the call - `account_suspended` (403, retry: no): The account is suspended - `forbidden` (403, retry: no): This credential may not use that option - `key_scope_denied` (403, retry: no): This key may not call this endpoint - `not_found` (404, retry: no, charged the endpoint's price where its data source billed the answer): The object does not exist, is private or was deleted - `result_not_found` (404, retry: no): No result under this request ID - `run_not_found` (404, retry: no): No run under this run ID - `unknown_endpoint` (404, retry: no): There is no such endpoint - `call_in_progress` (409, retry: same_key): The call under this idempotency key is still running; ask again with the same key shortly - `idempotency_conflict` (409, retry: after_fix): This idempotency key was used for a different request - `cursor_expired` (410, retry: no): The cursor expired; start again from the first page - `result_expired` (410, retry: no): Results are kept for 24 hours; this one is gone - `run_expired` (410, retry: no): This run has expired and starts no more calls - `rate_limited` (429, retry: yes): Too many requests, or too many calls in progress - `cost_cap_exceeded` (429, retry: yes): This account's allowance for today is used up - `uncharged_cost_limit` (429, retry: yes): Too many of this account's calls today returned nothing and were not charged; endpoints of this kind can be called again tomorrow (UTC) - `settlement_unknown` (500, retry: same_key, may have been charged): Whether this call settled is not known; ask again with the same idempotency key, or look it up by request ID - `internal_error` (500, retry: yes): The service failed - `upstream_failed` (502, retry: yes): No result came back this time and nothing was charged; retry shortly - `cursor_unavailable` (502, retry: yes): This cursor is unavailable just now; retry later or start again from the first page - `upstream_busy` (503, retry: yes): Busy just now; retry shortly - `capability_paused` (503, retry: yes): This endpoint is paused - `overloaded` (503, retry: yes): The service is busy; retry shortly - `timeout` (504, retry: yes): The data did not arrive in time; retry with the same idempotency key
- `5XX`: An error. Nothing was charged unless `charged` is null. - `invalid_params` (400, retry: after_fix, charged the endpoint's price where its data source billed the answer): A parameter is invalid - `request_not_served` (400, retry: after_fix): This combination of parameters cannot be served at present - `max_price_exceeded` (400, retry: after_fix): The most this call could cost is above the limit you set - `cursor_invalid` (400, retry: no): The cursor does not exist - `cursor_mismatch` (400, retry: after_fix): The cursor was issued for another endpoint or other parameters - `unauthorized` (401, retry: no): No credential was sent, or it is invalid, disabled or expired - `insufficient_balance` (402, retry: after_fix): The balance is too low - `key_budget_exceeded` (402, retry: after_fix): This key's spending limit does not cover the call - `run_budget_exceeded` (402, retry: no): This run's amount or call limit does not cover the call - `account_suspended` (403, retry: no): The account is suspended - `forbidden` (403, retry: no): This credential may not use that option - `key_scope_denied` (403, retry: no): This key may not call this endpoint - `not_found` (404, retry: no, charged the endpoint's price where its data source billed the answer): The object does not exist, is private or was deleted - `result_not_found` (404, retry: no): No result under this request ID - `run_not_found` (404, retry: no): No run under this run ID - `unknown_endpoint` (404, retry: no): There is no such endpoint - `call_in_progress` (409, retry: same_key): The call under this idempotency key is still running; ask again with the same key shortly - `idempotency_conflict` (409, retry: after_fix): This idempotency key was used for a different request - `cursor_expired` (410, retry: no): The cursor expired; start again from the first page - `result_expired` (410, retry: no): Results are kept for 24 hours; this one is gone - `run_expired` (410, retry: no): This run has expired and starts no more calls - `rate_limited` (429, retry: yes): Too many requests, or too many calls in progress - `cost_cap_exceeded` (429, retry: yes): This account's allowance for today is used up - `uncharged_cost_limit` (429, retry: yes): Too many of this account's calls today returned nothing and were not charged; endpoints of this kind can be called again tomorrow (UTC) - `settlement_unknown` (500, retry: same_key, may have been charged): Whether this call settled is not known; ask again with the same idempotency key, or look it up by request ID - `internal_error` (500, retry: yes): The service failed - `upstream_failed` (502, retry: yes): No result came back this time and nothing was charged; retry shortly - `cursor_unavailable` (502, retry: yes): This cursor is unavailable just now; retry later or start again from the first page - `upstream_busy` (503, retry: yes): Busy just now; retry shortly - `capability_paused` (503, retry: yes): This endpoint is paused - `overloaded` (503, retry: yes): The service is busy; retry shortly - `timeout` (504, retry: yes): The data did not arrive in time; retry with the same idempotency key

---

[API](https://skmtc.dev/data-x-api/apis/openapi.md) - [All operations](https://skmtc.dev/data-x-api/apis/openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/data-x-api/apis/openapi/revisions/929c12db713d?raw)
