{
  "openapi": "3.0.1",
  "info": {
    "title": "Twitter (X.com) Tweets & Profiles Scraper by Date Engagement",
    "description": "Twitter (X.com) Tweets & Profiles Scraper: Extract tweets and profile data by date and engagement, including text, authors, followers, views, likes, reposts, replies, hashtags, and timestamps. Analyze performance, research audiences, monitor competitors, and build targeted X datasets.",
    "version": "0.1",
    "x-build-id": "TPXZ8obQQV4h4Z5wx"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapier~twitter-x-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapier-twitter-x-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/scrapier~twitter-x-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapier-twitter-x-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/scrapier~twitter-x-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapier-twitter-x-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": "Accounts, profile URLs or search phrases",
            "type": "array",
            "description": "Accepted per line:\n- https://x.com/NASA  (profile URL)\n- NASA  or  @NASA  (handle)\n- \"artemis launch\"  (search phrase - needs the X session cookies in section 5)\n\nHandles run on the keyless profile timeline by default. When session cookies are supplied and 'Push filters to X' is on, handles are converted to a `from:handle` search so the date/engagement filters run SERVER-SIDE.",
            "default": [
              "https://x.com/elonmusk",
              "NASA"
            ],
            "items": {
              "type": "string"
            }
          },
          "maxTweets": {
            "title": "Max posts kept per target",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many posts survive filtering and reach the dataset, per target (1-100). The filters and the sort run BEFORE this cut, so you get the best 'max' rows, not the first ones X happened to send.",
            "default": 25
          },
          "sortOrder": {
            "title": "Order results by",
            "enum": [
              "newest",
              "oldest",
              "popular"
            ],
            "type": "string",
            "description": "Applied BEFORE the 'Max posts kept' cut.\n- newest: most recent first (search path asks X for the Latest tab)\n- oldest: oldest first\n- popular: highest like count first (search path asks X for the Top tab)",
            "default": "newest"
          },
          "withReplies": {
            "title": "Keep the account's own replies",
            "type": "boolean",
            "description": "Off = drop rows where the account was replying to someone (isReply = true). On = keep them.",
            "default": true
          },
          "includeUserInfo": {
            "title": "Attach the author profile block",
            "type": "boolean",
            "description": "Adds the nested `user` object (bio, join date, follower / following / post counts, avatar, website, location) to every row. Off removes the `user` key entirely.",
            "default": true
          },
          "postedAfter": {
            "title": "Posted on or after",
            "type": "string",
            "description": "YYYY-MM-DD, or a relative value like `7 days`, `3 months`, `1 year`. Leave blank for no lower bound.",
            "default": ""
          },
          "postedBefore": {
            "title": "Posted on or before",
            "type": "string",
            "description": "YYYY-MM-DD, or a relative value like `2 days`. Leave blank for no upper bound. X treats `until:` as exclusive of the following day.",
            "default": ""
          },
          "minLikes": {
            "title": "Minimum likes  (server-side on search)",
            "minimum": 0,
            "maximum": 100000000,
            "type": "integer",
            "description": "Drop posts under this like count. 0 = no floor. Becomes `min_faves:N` when the run uses X search.",
            "default": 0
          },
          "minRetweets": {
            "title": "Minimum reposts  (server-side on search)",
            "minimum": 0,
            "maximum": 100000000,
            "type": "integer",
            "description": "Drop posts under this repost count. 0 = no floor. Becomes `min_retweets:N` when the run uses X search.",
            "default": 0
          },
          "minReplies": {
            "title": "Minimum replies  (server-side on search)",
            "minimum": 0,
            "maximum": 100000000,
            "type": "integer",
            "description": "Drop posts under this reply count. 0 = no floor. Becomes `min_replies:N` when the run uses X search.",
            "default": 0
          },
          "minBookmarks": {
            "title": "Minimum bookmarks  (client-side)",
            "minimum": 0,
            "maximum": 100000000,
            "type": "integer",
            "description": "Drop posts under this bookmark count. X publishes bookmark_count on ~100% of posts but has no search operator for it, so this filter always runs after the fetch.",
            "default": 0
          },
          "minViews": {
            "title": "Minimum views  (client-side)",
            "minimum": 0,
            "maximum": 10000000000,
            "type": "integer",
            "description": "Drop posts under this view count. Views are missing on roughly a third of older posts - those rows are dropped by this floor because the count cannot be proven. 0 = no floor and nothing is dropped.",
            "default": 0
          },
          "minEngagementTotal": {
            "title": "Minimum total engagement  (client-side)",
            "minimum": 0,
            "maximum": 100000000,
            "type": "integer",
            "description": "Floor on likes + replies + reposts + quotes + bookmarks combined.",
            "default": 0
          },
          "minEngagementRatePct": {
            "title": "Minimum engagement rate %  (client-side)",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Floor on (total engagement / views) x 100. Posts with no view count are dropped when this is above 0, because the rate cannot be computed. 0 = no floor.",
            "default": 0
          },
          "tweetLanguage": {
            "title": "Language (ISO 639-1)",
            "type": "string",
            "description": "e.g. en, es, ja, pt. Blank = any language. Matched against the `lang` value X stamps on every post.",
            "default": ""
          },
          "onlyVerifiedAuthors": {
            "title": "Only posts from blue-verified accounts",
            "type": "boolean",
            "description": "Maps to `filter:blue_verified`. This is the paid checkmark, not legacy notability - the output column is named `isBlueVerified` so it cannot be misread.",
            "default": false
          },
          "preferServerSideFilters": {
            "title": "Push filters to X when possible",
            "type": "boolean",
            "description": "On + session cookies present + at least one filter set = handles are routed through `from:handle` X search so the date window and the likes/reposts/replies floors are applied by X before it sends the data. Off = always use the keyless profile timeline and filter locally. The row field `filterPath` records which route each row came from.",
            "default": true
          },
          "authToken": {
            "title": "auth_token cookie",
            "type": "string",
            "description": "The `auth_token` cookie value from an x.com session. Optional. Stored encrypted."
          },
          "ct0": {
            "title": "ct0 cookie",
            "type": "string",
            "description": "The `ct0` cookie value from the same x.com session. Sent as a cookie and as the x-csrf-token header. Optional, but required together with auth_token."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Attached to every outbound request, including credential discovery and the user-id lookup. Residential is the default because X rate-limits datacenter ranges harder; the run reports the remaining rate-limit budget it saw.",
            "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}