{
  "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 $3.00/1K.",
    "version": "1.0",
    "x-build-id": "PGJA8yqKXutOt8uwK"
  },
  "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}