{
  "openapi": "3.0.1",
  "info": {
    "title": "Xiaohongshu KOL Analytics — Pugongying Creator API",
    "description": "Brand-side KOL intelligence for Xiaohongshu (RedNote). Search Pugongying creators with B2B filters, pull fans demographics, ROI metrics, content tags, growth history, similar-KOL discovery — the data XHS uses to match brands with creators. By SIÁN Agency.",
    "version": "1.1",
    "x-build-id": "u9x2zHpgriyxuHAh7"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~xiaohongshu-kol-analytics/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-xiaohongshu-kol-analytics",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/sian.agency~xiaohongshu-kol-analytics/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-xiaohongshu-kol-analytics",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/sian.agency~xiaohongshu-kol-analytics/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-xiaohongshu-kol-analytics",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "operation"
        ],
        "properties": {
          "operation": {
            "title": "🎯 Operation — what do you want to extract?",
            "enum": [
              "kolInfo",
              "kolCoreData",
              "kolDataSummary",
              "kolCostEffective",
              "kolNoteRate",
              "kolFansTrend",
              "kolFansPortrait",
              "kolFansSummary",
              "kolContentTags",
              "kolFeatureTags",
              "similarKol",
              "bloggerSearch",
              "kolNoteList",
              "pgyNoteDetail"
            ],
            "type": "string",
            "description": "🎯 **PICK ONE OPERATION PER RUN.** Each run produces one clean dataset matching the chosen mode.\n\n**Creator profile & marketplace metrics**\n- **👤 KOL Info** — full Pugongying creator profile (handle, fans, pricing, tags, location)\n- **📊 KOL Core Data** — core marketplace metrics + daily-data array\n- **📈 KOL Data Summary** — aggregate summary by content business (daily-note / cooperate-note)\n- **💰 KOL Cost-Effectiveness** — ROI / CPM / surpass-rate benchmarks (highest-value B2B field)\n- **📋 KOL Note Rate** — note-performance rates per content tag\n\n**Audience intelligence**\n- **📊 KOL Fans Trend** — time-series of fan count or fan-increase (DAY_30 / DAY_90)\n- **👥 KOL Fans Portrait** — demographics (age / gender / geo / interests / devices)\n- **📊 KOL Fans Summary** — fan-base headline summary (active rate, engagement)\n\n**Content tags**\n- **🏷️ KOL Content Tags** — content category tags assigned by Pugongying\n- **🏷️ KOL Feature Tags** — audience feature tags assigned by Pugongying\n\n**Discovery**\n- **🔁 Similar KOLs** — XHS's own clustering output (~20 audience-overlapping creators)\n- **🔍 Blogger Search** — paginated B2B creator search with 9 filters (the headline discovery op)\n\n**Note-level data**\n- **📝 KOL Note List** — paginated note history with performance metrics\n- **📕 PGY Note Detail** — marketplace-side detailed view of a single note\n\n💡 **TIP:** Start with `Blogger Search` to find creator IDs, then drill into individual creators with `KOL Info` / `KOL Cost-Effectiveness` / `KOL Fans Portrait`.",
            "default": "bloggerSearch"
          },
          "userId": {
            "title": "👤 Creator ID (Pugongying KOL userId)",
            "type": "string",
            "description": "👤 **Required for every operation except Blogger Search.** Also required (in addition to noteId) for PGY Note Detail.\n\nThe Pugongying creator userId. You can find it:\n- In the `userId` field of any `Blogger Search` or `Similar KOLs` result row\n- In a creator's Xiaohongshu profile URL: `https://www.xiaohongshu.com/user/profile/{ID}`\n\n💡 **TIP:** Run `Blogger Search` first with a keyword + filters to surface qualified creator IDs, then drill into individual creators."
          },
          "noteId": {
            "title": "📕 Note ID (for PGY Note Detail)",
            "type": "string",
            "description": "📕 **Required for `PGY Note Detail` only.** The marketplace note ID. Find it in `KOL Note List` result rows (`noteId` field).\n\n⚠️ **Ignored** for all other operations."
          },
          "keyword": {
            "title": "🔍 Search Keyword (for Blogger Search)",
            "type": "string",
            "description": "🔍 **Optional for `Blogger Search`** — leave empty to browse the unfiltered top of the marketplace, or supply a keyword (Chinese or English) to filter:\n- `美食` (food)\n- `美妆` (beauty)\n- `母婴` (mom & baby)\n- `travel`\n\n💡 **TIP:** Combine `keyword` with the filter inputs below for tightly qualified shortlists.\n\n⚠️ **Ignored** for non-search operations."
          },
          "searchType": {
            "title": "🔍 Search Type",
            "enum": [
              "NICKNAME",
              "NOTE"
            ],
            "type": "string",
            "description": "**Blogger Search only.** Field the keyword is matched against:\n- `NICKNAME` — match creator handle (default)\n- `NOTE` — match notes the creator has published",
            "default": "NICKNAME"
          },
          "fansNumberLower": {
            "title": "👥 Min fans count",
            "minimum": 0,
            "type": "integer",
            "description": "**Blogger Search filter.** Minimum fans count (inclusive). E.g. `10000` to filter out micro-influencers below 10k."
          },
          "fansNumberUpper": {
            "title": "👥 Max fans count",
            "minimum": 0,
            "type": "integer",
            "description": "**Blogger Search filter.** Maximum fans count (inclusive). E.g. `1000000` to cap at 1M and avoid mega-influencer pricing."
          },
          "fansAge": {
            "title": "🎂 Fans age band",
            "enum": [
              "ALL",
              "LT_18",
              "AGE_18_24",
              "AGE_25_34",
              "AGE_35_44",
              "GT_44"
            ],
            "type": "string",
            "description": "**Blogger Search filter.** Required dominant age band of the creator's fans.",
            "default": "ALL"
          },
          "fansGender": {
            "title": "⚧ Fans gender skew",
            "enum": [
              "ALL",
              "MALE_HIGH",
              "FE_MALE_HIGH"
            ],
            "type": "string",
            "description": "**Blogger Search filter.** Required dominant gender skew of the creator's fans.",
            "default": "ALL"
          },
          "gender": {
            "title": "⚧ Creator gender",
            "enum": [
              "ALL",
              "MALE",
              "FEMALE"
            ],
            "type": "string",
            "description": "**Blogger Search filter.** Gender of the creator themselves.",
            "default": "ALL"
          },
          "contentTag": {
            "title": "🏷️ Content category tag",
            "type": "string",
            "description": "**Blogger Search filter.** Pugongying content category code (e.g. `beauty`, `food`, `fashion`). Leave empty for all categories."
          },
          "business": {
            "title": "📈 Business type (KOL Data Summary)",
            "enum": [
              "DAILY_NOTE",
              "COOPERATE_NOTE"
            ],
            "type": "string",
            "description": "**KOL Data Summary only.** Type of note volume to summarize.",
            "default": "DAILY_NOTE"
          },
          "dateType": {
            "title": "📅 Date range (KOL Fans Trend)",
            "enum": [
              "DAY_30",
              "DAY_90"
            ],
            "type": "string",
            "description": "**KOL Fans Trend only.** Time window for the fans trend series.",
            "default": "DAY_30"
          },
          "increaseType": {
            "title": "📊 Trend metric (KOL Fans Trend)",
            "enum": [
              "FANS_TOTAL",
              "FANS_INCREASE"
            ],
            "type": "string",
            "description": "**KOL Fans Trend only.** Which metric the time series tracks.",
            "default": "FANS_TOTAL"
          },
          "pageSize": {
            "title": "📄 Page size (KOL Note List)",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "**KOL Note List only.** Notes per page.",
            "default": 20
          },
          "maxPages": {
            "title": "📄 Max pages to fetch",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "📄 **Applies to paginated operations** (Blogger Search, KOL Note List). Ignored for single-record operations.\n\n- **Blogger Search:** ~20 creators per page\n- **KOL Note List:** ~20 notes per page (configurable via Page Size)\n\n💡 **TIP:** Start small (1–3 pages) to preview results before scaling up.\n\n⚠️ Hard cap: 50 pages to prevent runaway runs.",
            "default": 3
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}