{
  "openapi": "3.0.1",
  "info": {
    "title": "X Twitter Posts Search & Post Replies",
    "description": "X Twitter Posts Search & Post Replies — Scrape X (Twitter) posts by keyword, hashtag, or query and extract post details, author data, engagement metrics, and replies. Analyze conversations, trends, audience engagement, and social media activity with structured data.",
    "version": "0.1",
    "x-build-id": "HvbVg9Wm82PwsrTbz"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/api-empire~x-twitter-posts-search/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-api-empire-x-twitter-posts-search",
        "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~x-twitter-posts-search/runs": {
      "post": {
        "operationId": "runs-sync-api-empire-x-twitter-posts-search",
        "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~x-twitter-posts-search/run-sync": {
      "post": {
        "operationId": "run-sync-api-empire-x-twitter-posts-search",
        "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",
          "searchType"
        ],
        "properties": {
          "startUrls": {
            "title": "🎯 Targets to scrape — profiles, @users, keywords, or post links",
            "type": "array",
            "description": "📋 **Add one row per target.** Mix and match freely!\n\n✅ **What works:**\n• 🔗 Profile URL — `https://x.com/elonmusk`\n• 👤 Handle — `@NASA` or `BarackObama`\n• 🔤 Keyword(s) — `climate change` · `world cup final`\n• 🧠 Search syntax — `search: python from:NASA min_retweets:50`\n• 🔎 X search URL — `https://x.com/search?q=nasa&f=live`\n• #️⃣ Hashtag URL — `https://x.com/hashtag/NASA`\n• 🧵 Single post — `https://x.com/NASA/status/1234567890123456789` (its whole reply thread is pulled)\n\n💡 **Tip:** multi-word input = search · single word / URL = that account's timeline.",
            "items": {
              "type": "string"
            }
          },
          "maxTweets": {
            "title": "🔢 Max posts per target",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "🎯 **Cap collection per target** (URL / user / keyword).\n\n⚖️ Higher = more data + longer runs.\n💸 Tip: start small (10–50) to validate, then scale up. Remember every post also spends reply-thread calls when replies are enabled.",
            "default": 10
          },
          "searchType": {
            "title": "🔎 Search mode — Top or Latest",
            "enum": [
              "top",
              "latest"
            ],
            "type": "string",
            "description": "🏆 **Top** → popular & relevant posts (great for trends and analysis).\n🆕 **Latest** → newest first (perfect with **Time window** for monitoring).\n\n🧑 Note: on **profile** targets X exposes no sort parameter, so this setting changes nothing there — it applies to keyword/search targets only.",
            "default": "top"
          },
          "timeWindow": {
            "title": "📅 Time window — last N days",
            "minimum": 1,
            "type": "integer",
            "description": "🗓️ **Keep only posts newer than N days (UTC).**\n\n✅ Applied to **every** target type (profiles, searches and post links).\n🔕 Leave empty to collect up to *Max posts* regardless of date."
          },
          "timeWindowHours": {
            "title": "🕐 Time window — last N hours",
            "minimum": 1,
            "type": "integer",
            "description": "⏰ **Keep only posts newer than N hours (UTC).**\n\n✅ Applied to **every** target type.\n⚡ Use this for breaking-news / real-time monitoring.\n👑 Takes precedence over days if both are set."
          },
          "includeReplies": {
            "title": "💬 Collect the reply thread under every post",
            "type": "boolean",
            "description": "✅ **On** → each saved post carries a `replies[]` array and every reply is also written to a per-run `x-replies-<runId>` dataset.\n🔕 **Off** → posts only (behaves like the plain search actor).\n\n🔐 Requires X session cookies. Without them each row reports `replyFetchStatus: \"login_required\"` instead of pretending there are no replies.",
            "default": true
          },
          "maxRepliesPerPost": {
            "title": "🔢 Max replies per post",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "🎯 **Hard cap on replies collected per post.**\n\n📄 X returns ~36 replies per call. 25 ≈ 1 call, 200 ≈ 6 calls, 400 ≈ 12 calls.\n⏳ The budget is ~150 reply calls per 15 minutes per X account — a deep 400-reply pull on 12 posts will exhaust it.\n🧱 **Measured ceiling:** X stops serving new replies at roughly **350–410** per post no matter how deep you page.",
            "default": 25
          },
          "replyRankingMode": {
            "title": "🥇 Reply ranking — Relevance or Recency",
            "enum": [
              "relevance",
              "recency"
            ],
            "type": "string",
            "description": "🥇 **Relevance** → X's own ranked conversation (what a visitor sees first).\n🕒 **Recency** → newest replies first.\n\n📊 The two return genuinely different sets on the same post (measured 36 vs 34 rows with different first authors).",
            "default": "relevance"
          },
          "followHiddenReplies": {
            "title": "🫥 Follow hidden / low-ranked replies",
            "type": "boolean",
            "description": "🫥 X hides low-ranked replies behind a separate **\"Show more replies\"** cursor. On low-engagement posts that cursor is the *only* one served — without following it the post looks like it has zero replies.\n\n✅ Keep this on unless you only want the top-ranked thread.",
            "default": true
          },
          "includeNestedReplies": {
            "title": "🪜 Also fetch replies-to-replies (depth 2)",
            "type": "boolean",
            "description": "🪜 **On** → after the direct replies, the actor re-queries each reply that itself has replies and pulls its children (marked `isNested: true`, `replyDepth: 2`).\n\n💸 Costs **one extra call per expanded parent** (max 8 parents per post) and eats the same 150/15 min budget.",
            "default": false
          },
          "replyKeywords": {
            "title": "🔍 Keep only replies containing these words",
            "type": "array",
            "description": "🔍 **Case-insensitive substring filter applied to reply text.**\n\n✅ Matching replies carry the hits in `matchedKeywords[]`, and the post row aggregates them in `matchedReplyKeywords[]`.\n🔕 Leave empty to keep every reply.\n\n💡 Useful for complaint / question / brand monitoring inside big threads.",
            "items": {
              "type": "string"
            }
          },
          "authToken": {
            "title": "🍪 X `auth_token` cookie",
            "type": "string",
            "description": "🔑 The `auth_token` cookie value of a logged-in x.com session (a 40-character hex string).\n\n🔐 Stored encrypted. Combined with `ct0` it unlocks keyword search and reply threads.\n⚠️ Rate limits are shared across every run using the same X account."
          },
          "ct0": {
            "title": "🍪 X `ct0` cookie (CSRF token)",
            "type": "string",
            "description": "🔑 The `ct0` cookie value from the same x.com session. It is sent as the `x-csrf-token` header.\n\n🔐 Stored encrypted. Must come from the **same** browser session as `auth_token`."
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy — recommended for stable runs",
            "type": "object",
            "description": "🔒 **Off** → direct connection.\n✅ **On** → Apify Proxy (pick your groups in the UI).\n\n⭐ X session cookies tolerate IP changes well, so datacenter groups work too — RESIDENTIAL remains the safest default."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}