{
  "openapi": "3.0.1",
  "info": {
    "title": "🐦 X (Twitter) Tweet Scraper | Search, Hashtags & Profiles",
    "description": "Scrape tweets from X.com (Twitter) by search query, hashtag, username, or URL. Returns tweet text, engagement metrics, author info, media, and more. No login or API key required. Export to JSON, CSV, or XLSX.",
    "version": "1.0",
    "x-build-id": "2SY2EhZ6kG6JSfUz4"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~x-tweet-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-x-tweet-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/khadinakbar~x-tweet-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-x-tweet-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/khadinakbar~x-tweet-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-x-tweet-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": {
          "auth_token": {
            "title": "X Auth Token (auth_token cookie)",
            "type": "string",
            "description": "Your X.com session auth_token cookie. Required for search. Get it from your browser: F12 → Application tab → Cookies → x.com → auth_token. Keep this secret — it gives full access to your account."
          },
          "ct0": {
            "title": "X CSRF Token (ct0 cookie)",
            "type": "string",
            "description": "Your X.com ct0 CSRF token cookie. Must match the same session as auth_token. Get it from the same location: F12 → Application → Cookies → x.com → ct0."
          },
          "cookies": {
            "title": "Full Cookie String (alternative to auth_token + ct0)",
            "type": "string",
            "description": "Alternative: paste your full x.com cookie string here and auth_token + ct0 will be parsed automatically. Get it via F12 → Network tab → any x.com request → Request Headers → Cookie."
          },
          "searchQuery": {
            "title": "Search Query",
            "type": "string",
            "description": "Use when the user provides keywords, phrases, or X advanced search syntax (e.g. 'AI tools', '\"ChatGPT\" -filter:retweets', 'from:elonmusk'). Supports full X advanced search syntax. Use 'handles' instead when the user gives just a Twitter username."
          },
          "hashtags": {
            "title": "Hashtags",
            "type": "array",
            "description": "List of hashtags to scrape. Use when the user mentions a hashtag (e.g. '#AI', 'Web3'). The # symbol is optional. Each hashtag becomes a separate search query. Use 'searchQuery' for multi-word keyword searches.",
            "items": {
              "type": "string"
            }
          },
          "handles": {
            "title": "X Handles / Usernames",
            "type": "array",
            "description": "List of X (Twitter) usernames to scrape tweets from. Use when the user says 'get tweets from @username'. The @ symbol is optional. Each handle runs as a separate 'from:username' query up to maxTweetsPerQuery. Use 'startUrls' if the user pastes a full profile URL.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "Direct X.com or twitter.com URLs to scrape. Accepts profile pages (e.g. https://x.com/OpenAI) and search pages (e.g. https://x.com/search?q=AI). Use 'handles' for just a username, and 'searchQuery' for keyword searches.",
            "items": {
              "type": "object"
            }
          },
          "mentioning": {
            "title": "Mentioning (Find Tweets That Tag a User)",
            "type": "string",
            "description": "Find all tweets that mention this X username. Use for brand monitoring — e.g. enter 'OpenAI' to find every tweet that mentions @OpenAI. Do NOT use for scraping a user's own tweets — use 'handles' for that."
          },
          "sort": {
            "title": "Sort Order",
            "enum": [
              "Latest",
              "Top",
              "Both"
            ],
            "type": "string",
            "description": "How to sort search results. 'Latest' returns most recent tweets first (best for news/monitoring). 'Top' returns most-engaged tweets (best for finding viral content). 'Both' runs both simultaneously for maximum coverage but may return some duplicates.",
            "default": "Latest"
          },
          "maxTweetsPerQuery": {
            "title": "Max Tweets Per Query",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of tweets to collect per search query, hashtag, or handle. Set to 100 for research, 500+ for bulk data. Applied independently to each input source.",
            "default": 50
          },
          "lang": {
            "title": "Language Filter",
            "type": "string",
            "description": "ISO 639-1 language code to filter tweets (e.g. 'en' for English, 'es' for Spanish, 'fr' for French, 'de' for German, 'ja' for Japanese). Leave empty to collect all languages.",
            "default": ""
          },
          "startDate": {
            "title": "Start Date (Since)",
            "type": "string",
            "description": "Only collect tweets posted on or after this date. Format: YYYY-MM-DD (e.g. '2024-01-01'). Corresponds to the X 'since:' search operator. Leave empty for no start date limit."
          },
          "endDate": {
            "title": "End Date (Until)",
            "type": "string",
            "description": "Only collect tweets posted on or before this date. Format: YYYY-MM-DD (e.g. '2024-12-31'). Corresponds to the X 'until:' search operator. Leave empty for no end date limit."
          },
          "minimumLikes": {
            "title": "Minimum Likes",
            "minimum": 0,
            "type": "integer",
            "description": "Only return tweets with at least this many likes. Use to filter for high-engagement content. E.g. set to 100 to only get tweets with 100+ likes. Leave empty (0) for no minimum.",
            "default": 0
          },
          "minimumRetweets": {
            "title": "Minimum Retweets",
            "minimum": 0,
            "type": "integer",
            "description": "Only return tweets with at least this many retweets. Useful for finding viral or widely-shared content. Leave empty (0) for no minimum.",
            "default": 0
          },
          "minimumReplies": {
            "title": "Minimum Replies",
            "minimum": 0,
            "type": "integer",
            "description": "Only return tweets with at least this many replies. Useful for finding highly-discussed or controversial tweets. Leave empty (0) for no minimum.",
            "default": 0
          },
          "onlyVerified": {
            "title": "Only Verified Accounts",
            "type": "boolean",
            "description": "When enabled, only returns tweets from verified accounts (blue checkmark). Useful for filtering out low-credibility accounts and focusing on journalists, brands, or public figures.",
            "default": false
          },
          "onlyImages": {
            "title": "Only Tweets With Images",
            "type": "boolean",
            "description": "When enabled, only returns tweets that contain image attachments. Useful for visual content research or brand image monitoring.",
            "default": false
          },
          "onlyVideos": {
            "title": "Only Tweets With Videos",
            "type": "boolean",
            "description": "When enabled, only returns tweets that contain video attachments. Useful for video content analysis.",
            "default": false
          },
          "excludeReplies": {
            "title": "Exclude Reply Tweets",
            "type": "boolean",
            "description": "When enabled, filters out reply tweets from results. Useful for collecting only original content without conversation threads.",
            "default": false
          },
          "excludeRetweets": {
            "title": "Exclude Retweets",
            "type": "boolean",
            "description": "When enabled, filters out retweets (RT @...) from results. Useful for collecting only original tweets, not amplified/shared content.",
            "default": false
          },
          "includeSourceQuery": {
            "title": "Include Source Query in Output",
            "type": "boolean",
            "description": "When enabled, adds a 'source_query' field to each tweet record showing which search query, hashtag, or handle was used to find it. Useful when running multiple queries to trace which input produced each tweet.",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}