{
  "openapi": "3.0.1",
  "info": {
    "title": "Douyin Influencer Marketing Analytics — Xingtu KOL Data",
    "description": "Brand-side Douyin influencer intelligence from the Xingtu (星图) creator marketplace. Search creators with B2B filters; pull CPM/CPE price tiers, audience & follower distribution, cost-performance and conversion ROI, growth trends, and content/comment keyword analysis. By SIÁN Agency.",
    "version": "1.0",
    "x-build-id": "dvgftkUuYGmgDQOA9"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sian.agency~douyin-xingtu-kol-analytics/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sian.agency-douyin-xingtu-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~douyin-xingtu-kol-analytics/runs": {
      "post": {
        "operationId": "runs-sync-sian.agency-douyin-xingtu-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~douyin-xingtu-kol-analytics/run-sync": {
      "post": {
        "operationId": "run-sync-sian.agency-douyin-xingtu-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": [
              "creatorProfile",
              "creatorCoreMetrics",
              "creatorChannelMetrics",
              "audienceDistribution",
              "followerDistribution",
              "followerGrowthTrend",
              "costPerformance",
              "conversionAnalysis",
              "creatorSearch",
              "kolKeywordSearch",
              "itemReportTrends",
              "kolCommentKeywords",
              "kolContentKeywords",
              "showcaseItems"
            ],
            "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- **👤 Creator Profile** — full Xingtu creator profile (handle, followers, MCN, pricing, tags, location)\n- **📊 Creator Core Metrics** — marketing metrics + price tiers + industry tags\n- **📺 Creator Channel Metrics** — per-channel intro & info\n\n**Audience intelligence**\n- **👥 Audience Distribution** — device / consumption / interest distribution dimensions\n- **🌍 Follower Distribution** — fan geo / age / gender / device distribution\n- **📈 Follower Growth Trend** — daily follower count + deltas over a date range\n\n**ROI & cost**\n- **💰 Cost-Performance Analysis** — expected CPM / CPE / VV (the core pricing-vetting field)\n- **🔁 Conversion Analysis** — GPM / CPC / sales ranges, recommended product counts\n\n**Discovery**\n- **🔍 Creator Search** — paginated creator-square search with follower/price/tag filters (the headline discovery op)\n- **🔎 KOL Keyword Search** — simpler keyword creator search across Douyin / Toutiao / Xigua\n\n**Content & item intelligence**\n- **🎬 Item Report Trends** — time-series performance of a single video/item\n- **💬 Comment Keyword Analysis** — hot comment tokens (audience language)\n- **🏷️ Content Keyword Analysis** — content hot-keyword map\n- **🛍️ Showcase Items** — the creator's latest + top-performing videos/items\n\n💡 **TIP:** Start with `Creator Search` to find creator IDs, then drill into individual creators with `Creator Profile` / `Cost-Performance Analysis` / `Audience Distribution`.",
            "default": "creatorSearch"
          },
          "oAuthorId": {
            "title": "👤 Creator ID (oAuthorId / star_id)",
            "type": "string",
            "description": "👤 **Required for every operation except Creator Search, KOL Keyword Search, and Item Report Trends.**\n\nThe Xingtu creator (author) ID. You can find it:\n- In the `oAuthorId` / `starId` field of any `Creator Search` or `KOL Keyword Search` result row\n\n💡 **TIP:** Run `Creator Search` first with a keyword + filters to surface qualified creator IDs, then drill into individual creators."
          },
          "itemId": {
            "title": "🎬 Item ID (for Item Report Trends)",
            "type": "string",
            "description": "🎬 **Required for `Item Report Trends` only.** A Douyin video/item ID. Find it in `Showcase Items` result rows (`itemId` field).\n\n⚠️ **Ignored** for all other operations."
          },
          "keyword": {
            "title": "🔍 Search Keyword",
            "type": "string",
            "description": "🔍 **Required for `KOL Keyword Search`; optional for `Creator Search`** (leave empty to browse the unfiltered creator square). Chinese or English:\n- `美妆` (beauty)\n- `美食` (food)\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 (Creator Search)",
            "enum": [
              "NICKNAME",
              "NOTE"
            ],
            "type": "string",
            "description": "**Creator Search only.** Field the keyword is matched against.",
            "default": "NICKNAME"
          },
          "followerRange": {
            "title": "👥 Follower range (Creator Search)",
            "type": "string",
            "description": "**Creator Search filter.** Follower count range in 万 (10k) units, e.g. `10-100` for 100k–1M followers. Leave empty for all sizes."
          },
          "kolPriceType": {
            "title": "💰 Price type (Creator Search)",
            "type": "string",
            "description": "**Creator Search filter.** Pricing dimension to filter on, e.g. `视频1_20s` (1-20s video). Leave empty for all."
          },
          "kolPriceRange": {
            "title": "💰 Price range (Creator Search)",
            "type": "string",
            "description": "**Creator Search filter.** Price range in yuan paired with the price type, e.g. `10000-50000`. Leave empty for all."
          },
          "contentTag": {
            "title": "🏷️ Content tag (Creator Search)",
            "type": "string",
            "description": "**Creator Search filter.** Content category tag. Leave empty for all categories."
          },
          "platformSource": {
            "title": "🔎 Platform source (KOL Keyword Search)",
            "enum": [
              "_1",
              "_2",
              "_3"
            ],
            "type": "string",
            "description": "**KOL Keyword Search only.** Which platform to search.",
            "default": "_1"
          },
          "platform": {
            "title": "📺 Platform channel",
            "enum": [
              "SHORT_VIDEO",
              "LIVE_STREAMING",
              "PICTURE_TEXT",
              "SHORT_DRAMA"
            ],
            "type": "string",
            "description": "**Per-creator ops.** Which content channel the metrics describe.",
            "default": "SHORT_VIDEO"
          },
          "linkType": {
            "title": "🔗 Link type (Audience Distribution)",
            "enum": [
              "CONNECTED",
              "AWARE",
              "INTERESTED",
              "LIKE",
              "FOLLOW"
            ],
            "type": "string",
            "description": "**Audience Distribution only.** Audience funnel stage.",
            "default": "CONNECTED"
          },
          "authorType": {
            "title": "🌍 Fan type (Follower Distribution)",
            "enum": [
              "FAN",
              "DIE_HARD_FAN"
            ],
            "type": "string",
            "description": "**Follower Distribution only.** Which fan cohort to profile.",
            "default": "FAN"
          },
          "range": {
            "title": "📅 Range (Conversion Analysis)",
            "enum": [
              "DAY_30",
              "DAY_90"
            ],
            "type": "string",
            "description": "**Conversion Analysis only.** Time window for conversion metrics.",
            "default": "DAY_30"
          },
          "startDate": {
            "title": "📅 Start date (Follower Growth Trend)",
            "type": "string",
            "description": "**Follower Growth Trend only.** Start date in `yyyy-MM-dd`. Defaults to 30 days ago if empty."
          },
          "endDate": {
            "title": "📅 End date (Follower Growth Trend)",
            "type": "string",
            "description": "**Follower Growth Trend only.** End date in `yyyy-MM-dd`. Defaults to today if empty."
          },
          "onlyAssign": {
            "title": "🛍️ Only assigned items (Showcase Items)",
            "type": "boolean",
            "description": "**Showcase Items only.** Include only assigned (sponsored) items.",
            "default": false
          },
          "flowType": {
            "title": "🛍️ Flow type (Showcase Items)",
            "enum": [
              "EXCLUDE",
              "INCLUDE"
            ],
            "type": "string",
            "description": "**Showcase Items only.** Whether to include or exclude paid-flow items.",
            "default": "EXCLUDE"
          },
          "maxPages": {
            "title": "📄 Max pages to fetch",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "📄 **Applies to paginated operations** (Creator Search, KOL Keyword Search). Ignored for single-record operations.\n\n- ~20 creators per page\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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}