{
  "openapi": "3.0.1",
  "info": {
    "title": "Twitter (X.com) Tweets & Profiles Scraper",
    "description": "Scrape public Twitter X profiles with tweets, bios, followers, links, and engagement data. This actor captures structured profile insights at scale, supports keyword filtering, and exports clean JSON or CSV for research, analysis, and automation workflows.",
    "version": "0.1",
    "x-build-id": "sHszkH9ACgU2Sk0RW"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/api-empire~twitter-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-api-empire-twitter-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/api-empire~twitter-scraper/runs": {
      "post": {
        "operationId": "runs-sync-api-empire-twitter-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/api-empire~twitter-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-api-empire-twitter-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",
        "required": [
          "startUrls"
        ],
        "properties": {
          "startUrls": {
            "title": "🧵 Profiles to walk — URL, @handle, numeric user id, or keyword",
            "type": "array",
            "description": "One entry per target. Accepts https://x.com/NASA, NASA, @NASA, a numeric user id, or a search phrase. Profile targets run logged-out. Keyword targets are X search, which X serves to logged-in sessions only — supply the cookies below or they return nothing (the base actor returned nothing for keywords in every case). Example: [\"https://x.com/NASA\", \"@apify\"].",
            "default": [
              "https://x.com/NASA",
              "@apify"
            ],
            "items": {
              "type": "string"
            }
          },
          "maxTweets": {
            "title": "📌 Max posts per target (parents only — replies are budgeted apart)",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many timeline posts to keep per target. Replies and quote posts are NOT counted here — they have their own caps below, so raising the reply cap never costs you posts. X caps this surface at 100. Example: maxTweets=10 + maxRepliesPerTweet=25 → up to 10 post rows and up to 250 reply rows. Default is 10.",
            "default": 10
          },
          "sortOrder": {
            "title": "↕️ Order the posts before the cap is applied",
            "enum": [
              "newest",
              "oldest",
              "popular"
            ],
            "type": "string",
            "description": "newest = most recent first, oldest = earliest first, popular = highest like count first. The sort runs BEFORE the post cap, so 'popular' really returns the most-liked posts of the fetched window rather than reshuffling an arbitrary head. Default is newest.",
            "default": "newest"
          },
          "withReplies": {
            "title": "💬 Keep the profile's own replies among the posts",
            "type": "boolean",
            "description": "OFF removes posts that are themselves replies written by the profile you are scraping. This is about the profile's own timeline — it is NOT the conversation walk below, which collects what OTHER accounts replied to each post. Default is ON.",
            "default": true
          },
          "includeUserInfo": {
            "title": "👤 Attach the author profile block to every row",
            "type": "boolean",
            "description": "Adds the nested user object (bio, location, website, join date, follower / following / post / like counts, avatar, user id) to post rows AND to reply and quote rows, so you can score the people who replied. OFF drops the object from every row. Default is ON.",
            "default": true
          },
          "scrapeReplyThreads": {
            "title": "🗣️ Walk each post into its conversation",
            "type": "boolean",
            "description": "Turns each post into a thread: every reply X serves becomes its own dataset row with rowType=reply, isChild=true and parentId set to the post id. Needs the X session cookies further down. Default is ON.",
            "default": true
          },
          "maxRepliesPerTweet": {
            "title": "🔢 Max replies per post",
            "minimum": 0,
            "maximum": 200,
            "type": "integer",
            "description": "Cap on reply rows collected under ONE post. 0 = take everything X serves, up to the hard ceiling of 200 per post. Example: 5 posts × maxRepliesPerTweet=20 → at most 100 reply rows. Default is 25.",
            "default": 25
          },
          "replyDepth": {
            "title": "🪜 How deep to follow replies-to-replies",
            "minimum": 1,
            "maximum": 3,
            "type": "integer",
            "description": "1 = only direct replies to the post. 2 = also the nested replies X ships inline in the same response (free). 3 = additionally re-query each answered reply to pull its own children (costs one extra request per answered reply). Measured inline depth on X today tops out at 2, so 3 is the only setting that reaches further. Default is 2.",
            "default": 2
          },
          "threadRankingMode": {
            "title": "🥇 Which replies X should serve first",
            "enum": [
              "relevance",
              "recency"
            ],
            "type": "string",
            "description": "relevance = X's default ranking (top replies first). recency = newest replies first. Affects which replies you get when maxRepliesPerTweet cuts the thread short. Default is relevance.",
            "default": "relevance"
          },
          "minRepliesToFetch": {
            "title": "🚦 Skip posts with fewer than N replies",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Read from the post's own reply counter BEFORE any request is made, so silent posts cost nothing. 0 = try every post. Skipped posts are still emitted, with threadSkippedReason=below_min_replies. Default is 1.",
            "default": 1
          },
          "followHiddenReplies": {
            "title": "🫥 Follow 'show more replies' branches",
            "type": "boolean",
            "description": "Follows the hidden / ranked-down cursors X puts behind a 'Show more replies' link. OFF is faster and returns only the first-class replies. Default is ON.",
            "default": true
          },
          "includeQuoteTweets": {
            "title": "🔁 Also collect posts that quoted each post",
            "type": "boolean",
            "description": "Runs one X search per post for quoted_tweet_id:<post id> and emits every quoting post as its own row with rowType=quote, isChild=true, parentId = the quoted post. Needs the X session cookies. Default is ON.",
            "default": true
          },
          "maxQuoteTweetsPerTweet": {
            "title": "🔢 Max quote posts per post",
            "minimum": 0,
            "maximum": 50,
            "type": "integer",
            "description": "Cap on quote rows collected under ONE post. 0 = skip the quote search entirely. Default is 10, ceiling 50.",
            "default": 10
          },
          "authToken": {
            "title": "🔐 X auth_token cookie",
            "type": "string",
            "description": "Copy the auth_token cookie from a logged-in x.com browser tab (DevTools → Application → Cookies). Stored encrypted. Required for the conversation walk, quote posts and keyword search — X answers those three surfaces with HTTP 404 and an empty body for logged-out clients. Post rows do not need it."
          },
          "ct0": {
            "title": "🔐 X ct0 cookie (CSRF token)",
            "type": "string",
            "description": "The ct0 cookie from the same logged-in x.com tab. Sent as a cookie and as the x-csrf-token header. Must belong to the same session as auth_token, or X rejects the pair. Stored encrypted."
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy",
            "type": "object",
            "description": "Every outbound request goes through this proxy, including the guest-token activation and the query-id discovery. Apify Residential is the default because X answers datacenter ranges inconsistently.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}