{
  "openapi": "3.0.1",
  "info": {
    "title": "X Twitter Posts Search By Advanced Keyword Filters",
    "description": "X (Twitter) Posts Search — Search X posts using advanced keyword filters and extract post text, authors, hashtags, timestamps, replies, likes, reposts, views, and links. Analyze conversations, trends, audience engagement, and competitor activity with structured data.",
    "version": "0.1",
    "x-build-id": "HeeRwg9ePtZN7yj0Z"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/simpleapi~x-twitter-posts-search/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-simpleapi-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/simpleapi~x-twitter-posts-search/runs": {
      "post": {
        "operationId": "runs-sync-simpleapi-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/simpleapi~x-twitter-posts-search/run-sync": {
      "post": {
        "operationId": "run-sync-simpleapi-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 — keywords, @users, profile or search URLs",
            "type": "array",
            "description": "📋 **One row per target.** The filters below are applied to every keyword target.\n\n✅ **What works:**\n• 🔤 Keyword(s) — `climate change` · `world cup final`\n• #️⃣ Hashtag — `#NASA`\n• 🧠 Raw operator syntax — `search: python from:NASA min_retweets:50`\n• 🔗 X search URL — `https://x.com/search?q=nasa&f=live` (the query is extracted)\n• 🔗 Hashtag URL — `https://x.com/hashtag/NASA`\n• 👤 Handle / profile URL — `@NASA` · `https://x.com/elonmusk` (works logged-out)\n• ⭐ `*` — search on the advanced filters alone (e.g. only `fromAccounts` or `conversationId`)\n\n🚫 **Skipped:** single-post links (`…/status/123…`) and X system pages.\n\n💡 If any advanced filter is set, a bare one-word entry like `nasa` is treated as a **keyword**, not as the `@nasa` profile — X's profile timeline has no query parameters and would discard your filters.",
            "items": {
              "type": "string"
            }
          },
          "maxTweets": {
            "title": "🔢 Max posts per target",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "🎯 **Cap collection per target.**\n\n📄 X returns a fixed **20 posts per call** — 100 posts = 5 calls out of your ~187-call window.\n⚖️ Higher = more data + longer runs.",
            "default": 10
          },
          "searchType": {
            "title": "🔎 Search mode — Top or Latest",
            "enum": [
              "top",
              "latest"
            ],
            "type": "string",
            "description": "🏆 **Top** → X's popularity/relevance ranking; spans years.\n🆕 **Latest** → strictly newest first (measured monotonically descending, 20/20).\n\n📊 Genuinely different result sets — measured on `space telescope`, 20 posts each: **only 1 of 20 post ids overlapped**, median likes **3,779 (Top) vs 0 (Latest)**, Top spanned 2018-2026 while Latest covered the last few minutes.\n\n🧑 On **profile** targets X's timeline API has no sort parameter, so this setting does not change profile results.",
            "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 on **both** Top and Latest (the base actor silently ignored it on Top).\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⚡ Use for breaking-news / real-time monitoring.\n👑 Takes precedence over days if both are set."
          },
          "xAuthToken": {
            "title": "🍪 auth_token cookie",
            "type": "string",
            "description": "🔑 Your own X `auth_token` cookie. **Required for every keyword / operator target.**\n\n🔒 Stored encrypted (secret input). Never logged, never saved to the dataset.\n👤 Leave empty to run profile targets only — keyword targets will be reported as `login_required` instead of silently returning nothing."
          },
          "xCt0": {
            "title": "🍪 ct0 cookie (CSRF token)",
            "type": "string",
            "description": "🔑 Your own X `ct0` cookie, taken from the same browser session as `auth_token`. Both are needed together.\n\n🔒 Stored encrypted (secret input)."
          },
          "exactPhrase": {
            "title": "❝ Exact phrase",
            "type": "string",
            "description": "❝ Wraps your words in quotes → `\"space launch\"`.\n\n⚠️ **Honest caveat:** X stems and loosens phrase matching — **18 of 20** returned posts contained the literal phrase (measured live). Treat it as *strong* matching, not literal."
          },
          "anyOfWords": {
            "title": "🔀 Any of these words (OR)",
            "type": "array",
            "description": "🔀 Builds an OR group → `(rocket OR launch OR orbit)`.\n\n⚠️ Measured **15 of 20** returned posts contained one of the literal words — X also matches stems and linked-page text, so treat it as broad matching.\n\n💡 Multi-word entries are quoted automatically.",
            "items": {
              "type": "string"
            }
          },
          "excludeWords": {
            "title": "🚫 Exclude these words",
            "type": "array",
            "description": "🚫 Each word becomes `-word`, removing posts that contain it. Verified **20/20** live.",
            "items": {
              "type": "string"
            }
          },
          "hashtags": {
            "title": "#️⃣ Must contain these hashtags",
            "type": "array",
            "description": "#️⃣ Each entry becomes `#tag`. Verified **20/20** live; in 60 unfiltered baseline posts only 5 carried the tag.\n\n💡 The `#` is optional — `NASA` and `#NASA` both work.",
            "items": {
              "type": "string"
            }
          },
          "fromAccounts": {
            "title": "👤 Only posts FROM these accounts",
            "type": "array",
            "description": "👤 Becomes `from:handle`; several handles become an OR group `(from:a OR from:b)`.\n\n✅ Verified **20/20** for a single handle and **20/20** for a two-handle OR group — the returned author always matched.",
            "items": {
              "type": "string"
            }
          },
          "toAccounts": {
            "title": "↩️ Only replies TO these accounts",
            "type": "array",
            "description": "↩️ Becomes `to:handle` — replies addressed to that account. Verified **20/20** live (every row's `inReplyToScreenName` matched).",
            "items": {
              "type": "string"
            }
          },
          "mentionsAccounts": {
            "title": "📣 Must mention these accounts",
            "type": "array",
            "description": "📣 Becomes `@handle` — posts that mention the account anywhere in the text. Verified **20/20** live; **0 of 60** unfiltered baseline posts mentioned it.",
            "items": {
              "type": "string"
            }
          },
          "linkDomain": {
            "title": "🔗 Must link to this domain",
            "type": "string",
            "description": "🔗 Becomes `url:domain` — e.g. `nasa.gov`, `youtube.com`.\n\n🥇 The **strongest narrowing operator measured**: **19/20** returned posts carried a link to that domain, versus **1 of 60** unfiltered baseline posts. `https://` is stripped automatically."
          },
          "conversationId": {
            "title": "🧵 Only posts in this conversation",
            "type": "string",
            "description": "🧵 Becomes `conversation_id:<id>` — every post belonging to one thread, for a single search call.\n\n💡 Use the `conversationId` value from a previous run. Verified **20/20** same-conversation."
          },
          "contentTypes": {
            "title": "🎛️ Must be / must contain",
            "type": "array",
            "description": "🎛️ Each choice adds a `filter:` operator (all applied together, AND).\n\n📊 Measured hit rates (20 posts per filter, live): media 20/20 · images 19/20 · videos 20/20 · native video 20/20 · links 20/20 · replies 20/20 · verified author 20/20 · quote 20/20 · native reposts 20/20 (0 of 60 unfiltered baseline posts were reposts).\n\n⚠️ Combining mutually exclusive choices (e.g. images **and** videos) legitimately returns nothing.",
            "items": {
              "type": "string",
              "enum": [
                "media",
                "images",
                "videos",
                "native_video",
                "links",
                "replies",
                "verified",
                "quote",
                "nativeretweets"
              ],
              "enumTitles": [
                "🖼️ Has media",
                "📷 Has images",
                "🎬 Has videos",
                "📹 Native X video",
                "🔗 Has links",
                "💬 Is a reply",
                "✅ Verified author",
                "💭 Is a quote post",
                "🔁 Include native reposts"
              ]
            }
          },
          "excludeContentTypes": {
            "title": "🙅 Must NOT be / must NOT contain",
            "type": "array",
            "description": "🙅 Each choice adds a negated `-filter:` operator. Verified live: -links 20/20 · -replies 20/20 · -media 20/20.\n\nℹ️ There is deliberately **no “exclude reposts” toggle**: X's search index already excludes native reposts (0 of 60 unfiltered baseline posts were reposts), so such a toggle would appear to work while doing nothing.",
            "items": {
              "type": "string",
              "enum": [
                "links",
                "replies",
                "media"
              ],
              "enumTitles": [
                "🔗 No links",
                "💬 No replies",
                "🖼️ No media"
              ]
            }
          },
          "minLikes": {
            "title": "❤️ Minimum likes",
            "minimum": 0,
            "type": "integer",
            "description": "❤️ Becomes `min_faves:N`. Verified **20/20** at a 500-like threshold — every returned post met it, versus **0 of 60** unfiltered baseline posts."
          },
          "minReposts": {
            "title": "🔁 Minimum reposts",
            "minimum": 0,
            "type": "integer",
            "description": "🔁 Becomes `min_retweets:N`. Verified **20/20** at a 100-repost threshold."
          },
          "minReplies": {
            "title": "💬 Minimum replies",
            "minimum": 0,
            "type": "integer",
            "description": "💬 Becomes `min_replies:N`. Verified **20/20** at a 50-reply threshold."
          },
          "searchLanguage": {
            "title": "🌍 Post language",
            "enum": [
              "any",
              "en",
              "es",
              "fr",
              "de",
              "it",
              "pt",
              "nl",
              "ru",
              "uk",
              "tr",
              "pl",
              "sv",
              "da",
              "no",
              "fi",
              "cs",
              "el",
              "he",
              "ar",
              "fa",
              "hi",
              "bn",
              "ta",
              "th",
              "vi",
              "id",
              "ms",
              "tl",
              "ja",
              "ko",
              "zh"
            ],
            "type": "string",
            "description": "🌍 Becomes `lang:xx` — filters on the language X itself detected. Verified **20/20 Spanish** and **20/20 Japanese**; every row also carries the detected `lang` (120/120 populated) so you can check it yourself.",
            "default": "any"
          },
          "searchDateFrom": {
            "title": "📆 Posted after (since:)",
            "type": "string",
            "description": "📆 `YYYY-MM-DD`, or a relative phrase like `7 days ago`, `1 month`, `2 years`.\n\n✅ Verified **20/20** posts inside the requested bounds (`since:2024-01-01 until:2024-01-05`). Works on **Latest** too — historical windows are honoured."
          },
          "searchDateTo": {
            "title": "📆 Posted before (until:)",
            "type": "string",
            "description": "📆 `YYYY-MM-DD`, or a relative phrase like `3 days ago`.\n\n⚠️ X treats `until:` as exclusive of that day's later hours — use the day *after* your last wanted date to be safe."
          },
          "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 survive IP changes, so proxy choice is about your own IP hygiene, not about unblocking."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}