{
  "openapi": "3.0.1",
  "info": {
    "title": "TikTok Profile Scraper — Engagement Rate & Post Timing",
    "description": "TikTok Profile Scraper extracts data from any public TikTok profile, including username, bio, followers, following, likes, profile picture, and recent video metadata. Ideal for influencer research, competitor analysis, trend tracking, and automating structured TikTok profile insights at scale.",
    "version": "0.1",
    "x-build-id": "Had1bDgxQpeukm365"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/simpleapi~tiktok-profile-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-simpleapi-tiktok-profile-scraper",
        "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/simpleapi~tiktok-profile-scraper/runs": {
      "post": {
        "operationId": "runs-sync-simpleapi-tiktok-profile-scraper",
        "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/simpleapi~tiktok-profile-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-simpleapi-tiktok-profile-scraper",
        "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",
        "properties": {
          "creatorHandles": {
            "title": "🎯 Creators to analyse",
            "type": "array",
            "description": "TikTok usernames or profile URLs, one per line. Examples: mrbeast · @khaby.lame · https://www.tiktok.com/@zachking\n\nEach creator produces its own analytics report row plus one row per fetched video.",
            "items": {
              "type": "string"
            }
          },
          "postsPerCreator": {
            "title": "🔢 Posts to analyse per creator",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Size of the analysis window. The engagement rate and cadence numbers are computed over exactly these posts — a bigger window means a more representative report and a longer run. Default 20, maximum 500.",
            "default": 20
          },
          "includeCreatorReport": {
            "title": "📊 Emit the per-creator analytics report row",
            "type": "boolean",
            "description": "Adds one `type: creator_report` row per creator carrying the engagement rollup, the posting cadence and the ranked shortlist. Turn off to receive only the raw video rows. Report rows are not billed.",
            "default": true
          },
          "rankBy": {
            "title": "🏆 Rank the top-posts shortlist by",
            "enum": [
              "engagementRate",
              "plays",
              "diggs",
              "shares"
            ],
            "type": "string",
            "description": "Metric used to order the shortlist inside the report row and to flag `isTopPost` on video rows. Engagement rate = (likes + comments + shares) ÷ views.",
            "default": "engagementRate"
          },
          "topPostsLimit": {
            "title": "🥇 Shortlist length",
            "minimum": 0,
            "maximum": 50,
            "type": "integer",
            "description": "How many posts to keep in the ranked shortlist. Example: 5 → the 5 best posts of the fetched window. Set 0 to skip the shortlist. Default 5, maximum 50.",
            "default": 5
          },
          "postOrdering": {
            "title": "↕️ Ordering of the fetched window",
            "enum": [
              "latest",
              "popular",
              "oldest"
            ],
            "type": "string",
            "description": "Client-side ordering of the posts this run fetched. TikTok's profile video endpoint always returns a newest-first window and ignores server-side sort requests, so 'oldest' means the oldest posts *within the fetched window* — not the oldest posts on the account.",
            "default": "latest"
          },
          "windowStartDate": {
            "title": "📅 Analyse posts published after",
            "type": "string",
            "description": "Absolute date (YYYY-MM-DD) or relative days ago (e.g. 30 = last 30 days)."
          },
          "windowEndDate": {
            "title": "📅 Analyse posts published before",
            "type": "string",
            "description": "Absolute date (YYYY-MM-DD) or relative days ago (e.g. 0 = today)."
          },
          "minHearts": {
            "title": "❤️ Minimum likes per post (≥)",
            "minimum": 1,
            "type": "integer",
            "description": "Keep only posts with at least this many likes. Example: 10000 → the report describes that creator's high-performing posts only."
          },
          "maxHearts": {
            "title": "🤍 Maximum likes per post (<)",
            "minimum": 1,
            "type": "integer",
            "description": "Keep only posts below this like count. Useful for profiling a creator's ordinary posts without their outliers."
          },
          "profiles": {
            "title": "👤 profiles (base-compatible alias)",
            "type": "array",
            "description": "Same as Creators to analyse. Present so input built for the standard TikTok profile scraper runs unchanged. If both are supplied, this one wins.",
            "items": {
              "type": "string"
            }
          },
          "resultsPerPage": {
            "title": "🔢 resultsPerPage (base-compatible alias)",
            "minimum": 1,
            "maximum": 500,
            "type": "integer",
            "description": "Same as Posts to analyse per creator. Capped at 500."
          },
          "profileSorting": {
            "title": "↕️ profileSorting (base-compatible alias)",
            "enum": [
              "latest",
              "popular",
              "oldest"
            ],
            "type": "string",
            "description": "Same as Ordering of the fetched window (client-side)."
          },
          "oldestPostDateUnified": {
            "title": "📅 oldestPostDateUnified (base-compatible alias)",
            "type": "string",
            "description": "Same as Analyse posts published after."
          },
          "newestPostDate": {
            "title": "📅 newestPostDate (base-compatible alias)",
            "type": "string",
            "description": "Same as Analyse posts published before."
          },
          "leastDiggs": {
            "title": "❤️ leastDiggs (base-compatible alias)",
            "minimum": 1,
            "type": "integer",
            "description": "Same as Minimum likes per post."
          },
          "mostDiggs": {
            "title": "🤍 mostDiggs (base-compatible alias)",
            "minimum": 1,
            "type": "integer",
            "description": "Same as Maximum likes per post."
          },
          "profileScrapeSections": {
            "title": "📂 profileScrapeSections (base-compatible alias)",
            "type": "array",
            "description": "Accepted for compatibility. This actor analyses a creator's own videos; reposts are not part of the engagement report.",
            "items": {
              "type": "string",
              "enum": [
                "videos",
                "reposts"
              ]
            }
          },
          "maxFollowersPerProfile": {
            "title": "👥 maxFollowersPerProfile (base-compatible alias)",
            "minimum": 1,
            "type": "integer",
            "description": "Skip posts whose author has this many followers or more."
          },
          "maxFollowingPerProfile": {
            "title": "👥 maxFollowingPerProfile (base-compatible alias)",
            "minimum": 1,
            "type": "integer",
            "description": "Skip posts whose author follows this many accounts or more."
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy",
            "type": "object",
            "description": "Optional. The actor starts direct and escalates to datacenter, then residential, only while a creator has produced no rows yet."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}