View raw JSON
{
"type": "object",
"required": [],
"properties": {
"body": {
"type": "object",
"title": "BloggerListReq",
"properties": {
"coop": {
"anyOf": [
{
"type": "object",
"title": "CoopFilter",
"properties": {
"cpuv": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Reach Scale\" median store-visit UV from cross-domain sponsored notes over the last 30 days. **This is a count, not a cost** (web presets: 500–1000 / 1000–2000 / 2000–5000 / 5000–10000 / 10000+). To filter by cost per store visit, use estimate_cpuv instead."
},
"pic_cpm": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Estimated CPM\" for image-text notes"
},
"industry": {
"anyOf": [
{
"enum": [
"不限",
"美妆个护",
"食品饮料",
"母婴",
"3c及电器",
"日用百货",
"服装配饰",
"互联网",
"生活服务",
"家居建材",
"汽车"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Industry",
"examples": [
"美妆个护"
],
"description": "\"Recent collaboration industry\""
},
"brand_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 20
},
{
"type": "null"
}
],
"title": "Brand Ids",
"description": "\"Recent collaboration brands\": list of brand userIds"
},
"pic_price": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Collaboration price\" fixed rate for image-text notes (CNY)"
},
"video_cpm": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Estimated CPM\" for video notes"
},
"imp_median": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Reach Scale\" median impressions (sponsored notes)"
},
"order_count": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Open orders\": number of orders the blogger has **accepted but not yet completed**. This is the current backlog, not the lifetime collaboration count — do not use this to find experienced bloggers."
},
"read_median": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Reach Scale\" median reads (sponsored notes)"
},
"video_price": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Collaboration price\" fixed rate for video notes (CNY)"
},
"inter_median": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Reach Scale\" median engagement (sponsored notes)"
},
"estimate_cpuv": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Estimated cost per store visit\""
},
"exclude_brands": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Exclude Brands",
"description": "Used with brand_ids: true = exclude bloggers who have collaborated with these brands"
},
"pic_read_price": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Estimated cost per read\" for image-text notes"
},
"pic_engage_cost": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Estimated cost per engagement\" for image-text notes"
},
"reply_48h_ratio": {
"anyOf": [
{
"type": "object",
"title": "PercentRange",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
80
],
"description": "Maximum (inclusive), percentage points 0–100"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
20
],
"description": "Minimum (inclusive), percentage points 0–100"
}
},
"description": "Percentage-point range: enter values 0–100, e.g. `40` means 40% (**not 0.4**).\n\nCalibration follows the Pugongying web UI: the threshold for thousand-like note ratio is written as `{\"40%以上\": [40, null]}`, `{\"10%以下\": [null, 10]}` — the API receives 40 / 10.\n\n**What this catches and what it doesn't:**\n* Catches oversized values — entering 200 or 9500 (as basis points or raw counts) returns 422, whereas the generic RangeFilter cap of 1e12 would have let them through.\n* **Does not catch undersized values** — entering 0.4 is still valid because 0.4% is a legitimate value; the type system cannot distinguish \"meant 40% but typed 0.4\" from \"actually wants 0.4%\". This can only be addressed through documentation.",
"x-readme-ref-name": "PercentRange",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Collaboration reliability\" 48-hour invitation reply rate: enter 0–100 as percentage points, e.g. `80` means 80%"
},
"video_read_price": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Estimated cost per read\" for video notes"
},
"video_engage_cost": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Estimated cost per engagement\" for video notes"
}
},
"description": "Sponsored note metrics — corresponds to the \"Sponsored Notes\" section on the web UI (collaboration performance + data performance).",
"x-readme-ref-name": "CoopFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Sponsored note metric filters"
},
"fans": {
"anyOf": [
{
"type": "object",
"title": "FansFilter",
"properties": {
"age": {
"anyOf": [
{
"enum": [
0,
1,
2,
3,
4,
5
],
"type": "integer"
},
{
"type": "null"
}
],
"title": "Age",
"examples": [
3
],
"description": "\"Fan age bracket\": 0 = any, 1 = under 18, 2 = 18–24, 3 = 25–34, 4 = 35–44, 5 = over 44 (highest share)"
},
"count": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Follower count\" range"
},
"gender": {
"anyOf": [
{
"enum": [
0,
1,
2
],
"type": "integer"
},
{
"type": "null"
}
],
"title": "Gender",
"examples": [
2
],
"description": "\"Fan gender\": 0 = any, 1 = predominantly male, 2 = predominantly female"
},
"location": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Location",
"examples": [
[
"上海"
]
],
"description": "\"Fan location\": where the fans are based. **Just enter place names** (e.g. [\"Shanghai\"], [\"Hangzhou\"]); the upstream will auto-complete the full path. You can also supply a full path like \"China Zhejiang Hangzhou\". Note this tree **only goes down to city level** (no districts); available names come from the **fansAreas** field in /get_blogger_filter_options."
},
"child_age": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
0,
2,
3,
4,
5,
6,
7,
8
],
"type": "integer"
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Child Age",
"description": "\"Parenting stage\": 0 = trying to conceive, 2 = 0–6 months, 3 = 7–12 months, 4 = 1–3 years, 5 = 4–6 years, 6 = 7–12 years, 7 = first trimester, 8 = third trimester"
},
"device_brand": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"苹果",
"华为",
"OPPO",
"VIVO",
"荣耀",
"小米",
"一加",
"魅族",
"中兴",
"联想"
],
"type": "string"
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Device Brand",
"examples": [
[
"苹果"
]
],
"description": "\"Phone brand\""
},
"device_price": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"0-999",
"1000-1999",
"2000-2999",
"3000-3999",
"4000-4999",
"5000-5999",
"6000-6999",
"7000-7999",
"8000+"
],
"type": "string"
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Device Price",
"examples": [
[
"3000-3999"
]
],
"description": "\"Phone price tier\", e.g. 3000-3999 / 8000+"
},
"marital_status": {
"anyOf": [
{
"enum": [
-1,
0,
1
],
"type": "integer"
},
{
"type": "null"
}
],
"title": "Marital Status",
"description": "\"Marital status\": -1 = any, 0 = single, 1 = married"
},
"consumption_level": {
"anyOf": [
{
"enum": [
-1,
0,
1,
2
],
"type": "integer"
},
{
"type": "null"
}
],
"title": "Consumption Level",
"description": "\"Spending level\": -1 = any, 0 = low, 1 = medium, 2 = high"
}
},
"description": "Fan demographics — corresponds to the \"Fan Profile\" section on the web UI (follower count / age / gender / location / marital status / spending / parenting stage / device).",
"x-readme-ref-name": "crawlers__xiaohongshu__pgy__pgy_filters__FansFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Fan demographic filters"
},
"goal": {
"anyOf": [
{
"type": "object",
"title": "GoalFilter",
"properties": {
"market_target": {
"anyOf": [
{
"enum": [
"estimateAllCpm",
"mAccumImpNum",
"readCost",
"mValidRawReadFeedNum",
"estimateEngageCost",
"mEngagementNum90d",
"estimateCpuv",
"mCpuvNum"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Market Target",
"examples": [
"mAccumImpNum"
],
"description": "\"Marketing objective\": the web UI uses a three-level selection (objective → metric → stat type); supply the final leaf code — `estimateAllCpm` Awareness/Impression performance/Cost, `mAccumImpNum` Awareness/Impression performance/Scale, `readCost` Awareness/Read performance/Cost, `mValidRawReadFeedNum` Awareness/Read performance/Scale, `estimateEngageCost` Seeding/Engagement performance/Cost, `mEngagementNum90d` Seeding/Engagement performance/Scale, `estimateCpuv` Conversion/Store-visit performance/Cost, `mCpuvNum` Conversion/Store-visit performance/Scale"
}
},
"description": "Cooperation goal: match bloggers by marketing objective (awareness / seeding / conversion).\n\nTo target bloggers by audience segment, use `BloggerAttrFilter.audience20` (the 20 audience archetypes) instead.",
"x-readme-ref-name": "GoalFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Marketing goal filters"
},
"live": {
"anyOf": [
{
"type": "object",
"title": "LiveFilter",
"properties": {
"avg_gmv": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Average GMV per session\": the blogger's average live-streaming GMV (CNY) over the **last 90 days**. Note the window is 90 days, unlike live_count which uses 30 days."
},
"avg_viewer": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Average viewers per session\": the blogger's average live-streaming viewer count over the **last 90 days**. Note the window is 90 days, unlike live_count which uses 30 days."
},
"live_count": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Live sessions in the last 30 days\""
}
},
"description": "Live-streaming data — corresponds to the \"Live Data\" section on the web UI.",
"x-readme-ref-name": "LiveFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Live-streaming metric filters"
},
"note": {
"anyOf": [
{
"type": "object",
"title": "NoteFilter",
"properties": {
"note_type": {
"anyOf": [
{
"enum": [
0,
1,
2
],
"type": "integer"
},
{
"type": "null"
}
],
"title": "Note Type",
"examples": [
2
],
"description": "\"Note type\": 0 = any, 1 = primarily image-text, 2 = primarily video"
},
"imp_median": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Median impressions\""
},
"read_median": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Median reads\""
},
"inter_median": {
"anyOf": [
{
"type": "object",
"title": "RangeFilter",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
50000
],
"description": "Maximum value (inclusive); omit for unlimited"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 1000000000000,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
10000
],
"description": "Minimum value (inclusive)"
}
},
"description": "Numeric range corresponding to the \"Custom\" input on the web UI.\n\n- Both ends are optional: omitting `min` defaults to 0; omitting `max` means unlimited.\n- At least one endpoint is required, otherwise returns 422.",
"x-readme-ref-name": "RangeFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Median engagement\""
},
"thousand_like_percent": {
"anyOf": [
{
"type": "object",
"title": "PercentRange",
"properties": {
"max": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Max",
"examples": [
80
],
"description": "Maximum (inclusive), percentage points 0–100"
},
"min": {
"anyOf": [
{
"type": "number",
"maximum": 100,
"minimum": 0
},
{
"type": "null"
}
],
"title": "Min",
"examples": [
20
],
"description": "Minimum (inclusive), percentage points 0–100"
}
},
"description": "Percentage-point range: enter values 0–100, e.g. `40` means 40% (**not 0.4**).\n\nCalibration follows the Pugongying web UI: the threshold for thousand-like note ratio is written as `{\"40%以上\": [40, null]}`, `{\"10%以下\": [null, 10]}` — the API receives 40 / 10.\n\n**What this catches and what it doesn't:**\n* Catches oversized values — entering 200 or 9500 (as basis points or raw counts) returns 422, whereas the generic RangeFilter cap of 1e12 would have let them through.\n* **Does not catch undersized values** — entering 0.4 is still valid because 0.4% is a legitimate value; the type system cannot distinguish \"meant 40% but typed 0.4\" from \"actually wants 0.4%\". This can only be addressed through documentation.",
"x-readme-ref-name": "PercentRange",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "\"Thousand-like note ratio\": enter 0–100 as percentage points, e.g. `20` means 20% (**not 0.2**)"
}
},
"description": "Organic note data — corresponds to the \"Organic Notes\" section on the web UI (natural traffic performance over the last 30 days).",
"x-readme-ref-name": "NoteFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Organic note metric filters"
},
"sort": {
"enum": [
"desc",
"asc"
],
"type": "string",
"title": "Sort",
"default": "desc",
"examples": [
"desc"
],
"description": "Sort direction: desc or asc"
},
"flags": {
"anyOf": [
{
"type": "object",
"title": "FlagFilter",
"properties": {
"is_star": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Star",
"description": "\"Celebrity\""
},
"high_quality": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "High Quality",
"description": "\"High-quality blogger\""
},
"note_and_live": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Note And Live",
"description": "\"Open to both notes and live collaboration\""
},
"activity_codes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Activity Codes",
"description": "\"Trending campaigns\": supply the code from each item in the activities list returned by `/blogger/filter-options`"
},
"industry_first": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Industry First",
"examples": [
"美妆个护"
],
"description": "\"Industry-recommended bloggers\" top-level industry name (e.g. Beauty & Personal Care); the platform recommends bloggers specific to that industry"
},
"exclude_invited": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Exclude Invited",
"description": "\"Exclude already-invited bloggers\""
},
"industry_second": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Industry Second",
"description": "\"Industry-recommended bloggers\" second-level industry name (used with industry_first; values come from taxonomy2Tags under industryTags in `/blogger/filter-options`)"
},
"filter_intention": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Filter Intention",
"description": "\"Industry intention match\""
},
"new_high_quality": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "New High Quality",
"description": "\"Rising-star blogger\""
},
"exclude_fans_down": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Exclude Fans Down",
"description": "\"Exclude bloggers losing followers\""
},
"exclude_cooperated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Exclude Cooperated",
"description": "\"Exclude previously collaborated bloggers\""
},
"exclude_low_active": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Exclude Low Active",
"description": "\"Exclude low-activity bloggers\""
}
},
"description": "Boolean flags — corresponds to the \"Platform Recommendations\" (curated bloggers / trending campaigns) and \"Standard Exclusions\" (one-click exclusions) sections on the web UI.",
"x-readme-ref-name": "FlagFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Boolean flag filters"
},
"column": {
"enum": [
"comprehensiverank",
"fansCount",
"price",
"clickNum",
"mEngagementNum",
"accumCommonImpMedinNum30d",
"accumPicCommonImpMedinNum30d",
"accumVideoCommonImpMedinNum30d",
"pictureClickMidNum",
"videoClickMidNum",
"pictureInterMidNum",
"videoInterMidNum",
"thousandLikePercent30",
"pictureThousandLikePercent30",
"videoThousandLikePercent30",
"hundredLikePercent30",
"pictureHundredLikePercent30",
"videoHundredLikePercent30",
"videoFinishRate",
"accumCoopImpMedinNum30d",
"readMidCoop30",
"interMidCoop30",
"mCpuvNum30d",
"picturePrice",
"videoPrice",
"pictureReadCost",
"videoReadCost",
"inviteReply48hNumRatio",
"fans30GrowthRate",
"fansActiveIn28dLv",
"fansEngageNum30dLv",
"kliveCnt30d",
"avgLiveViewerNum",
"avgAgmv90d"
],
"type": "string",
"title": "Column",
"default": "comprehensiverank",
"examples": [
"comprehensiverank"
],
"description": "Sort column; 34 options available — see the sort field table in the endpoint documentation"
},
"blogger": {
"anyOf": [
{
"type": "object",
"title": "BloggerAttrFilter",
"properties": {
"gender": {
"anyOf": [
{
"enum": [
"男",
"女"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Gender",
"examples": [
"女"
],
"description": "\"Gender\": 男 / 女 (enter Chinese characters, not numbers)"
},
"signed": {
"anyOf": [
{
"enum": [
-1,
0,
1
],
"type": "integer"
},
{
"type": "null"
}
],
"title": "Signed",
"examples": [
0
],
"description": "\"Agency affiliation\": -1 = any, 0 = independent blogger, 1 = agency-affiliated blogger"
},
"location": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Location",
"examples": [
[
"上海"
]
],
"description": "\"Location\": where the blogger is based. **Just enter place names** — any level works (province/city/district): [\"Shanghai\"], [\"Hangzhou\"], [\"Shangcheng District\"] are all valid; multiple values are OR-ed. Full paths like \"China Zhejiang Hangzhou\" also work and will be auto-resolved. Available names come from the **areas** field in /get_blogger_filter_options (down to district level)."
},
"audience20": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Audience20",
"examples": [
[
"自在户外"
]
],
"description": "\"20 audience archetypes\": supply the top-level name (e.g. 自在户外), or the two-level format \"top top-sub\" (e.g. \"自在户外 自在户外-挑战极限者\"). Full list available in the audience20 field of `/blogger/filter-options`."
},
"note_scene": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Note Scene",
"examples": [
[
"汽车 理性决策 选车攻略 政策"
]
],
"description": "\"Note category\": supply the **space-separated full path** (category level-1 level-2 level-3), e.g. \"汽车 理性决策 选车攻略 政策\". Values reference the \"Note Category\" dropdown on the Pugongying \"Find Bloggers\" page (no dictionary API available for this field); leave empty if unsure."
},
"content_tag": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Content Tag",
"examples": [
[
"美妆"
]
],
"description": "\"Blogger category\": supply a category name; there are 29 top-level options — 全部/美妆/护肤/个人护理/母婴/时尚/美食/家居家装/影视综资讯/运动健身/宠物/文化艺术/兴趣爱好/生活记录/教育/职场/情感/摄影/游戏/科技数码/出行旅游/音乐/搞笑/健康养生/汽车/婚嫁/商业财经/素材/其他. You can also supply a second-level name under any top-level category. Note this is a different taxonomy from \"Industry\" (coop.industry)."
},
"feature_tags": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Feature Tags",
"examples": [
[
"vlog"
]
],
"description": "\"Content strengths\": supply the **second-level name** from featureTags in `/blogger/filter-options` (e.g. vlog / 探店 / 测评)"
},
"content_theme": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Content Theme",
"examples": [
[
"汽车特色"
]
],
"description": "\"Content theme\": supply the **top-level label** from contentTheme in `/blogger/filter-options` (e.g. 汽车特色 / 通用). Only top-level is supported; entering a child label or ID will return no results."
},
"personal_tags": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Personal Tags",
"examples": [
[
"妈妈"
]
],
"description": "\"Blogger persona\": supply the **leaf tagName** from the three-level personalTagsV2 tree in `/blogger/filter-options` (family role / professional identity / distinctive background → group → leaf, e.g. 妈妈)."
},
"industry_crowd": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Industry Crowd",
"examples": [
[
"15795914"
]
],
"description": "\"Industry-specific profile\": supply the **deepest leaf value** (a numeric string ID, e.g. 15795914; over 1600 total) from automotiveIndustryTag in `/blogger/filter-options`. Entering a label or intermediate-level ID will return no results."
},
"consumer_behavior": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"maxItems": 30
},
{
"type": "null"
}
],
"title": "Consumer Behavior",
"description": "\"Estimated consumer behavior\": supply the leaf path/label from consumerBehavior in `/blogger/filter-options`. This feature is account-gated; if the dictionary returns null, it is unavailable for the current account."
}
},
"description": "Blogger attributes: category, persona, content strengths, audience archetypes, gender, location, agency affiliation, etc.\n\nFor hierarchical options (category / persona / content strengths / content themes / 20 audience archetypes / industry-specific profiles / estimated consumer behavior), first call `/api/v2/pgy/blogger/filter-options` to retrieve valid values; each field description specifies which level to use.",
"x-readme-ref-name": "BloggerAttrFilter",
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Blogger attribute filters"
},
"keyword": {
"type": "string",
"title": "Keyword",
"default": "",
"examples": [
"咖啡"
],
"maxLength": 50,
"description": "Search keyword; leave empty to filter without searching"
},
"page_num": {
"type": "integer",
"title": "Page Num",
"default": 1,
"maximum": 250,
"minimum": 1,
"examples": [
1
],
"description": "Page number, 1–250 (upstream only exposes the first 5000 results)"
},
"page_size": {
"type": "integer",
"title": "Page Size",
"default": 20,
"maximum": 20,
"minimum": 1,
"examples": [
20
],
"description": "Results per page, 1–20 (the web UI uses 20; recommended to keep 20)"
},
"search_type": {
"enum": [
0,
1
],
"type": "integer",
"title": "Search Type",
"default": 1,
"examples": [
1
],
"description": "1 = find bloggers by note keyword (default), 0 = search by nickname"
},
"similar_word": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Similar Word",
"description": "Blogger nickname used with similar_user_id; for display echo only, does not affect results"
},
"brand_user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand User Id",
"examples": [
"5dcfa5370000000001006030"
],
"description": "Brand/advertiser user ID; optional"
},
"similar_user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Similar User Id",
"examples": [
"5c668b3e0000000012021605"
],
"description": "Find similar bloggers: supply a blogger's userId to return similar bloggers, **and you can stack all the filters below on top** (this is the key difference from /get_blogger_similar)"
}
},
"x-readme-ref-name": "BloggerListReq",
"additionalProperties": false
},
"queryParams": {
"type": "object",
"properties": {},
"additionalProperties": true
}
},
"additionalProperties": false
}
