X API & Twitter API Ruby SDK by Xquik

Use this X API & Twitter API SDK to work with X from Ruby. It works as a Twitter scraper & tweet scraper for search, profiles & followers. Scrape Twitter timelines, lists, communities & trends into typed results. Manage media, webhooks, monitors & X automation with typed requests. It provides a Twitter API alternative through documented Xquik REST routes.

Xquik is the world's fastest and cheapest X Twitter scraper service with the most complete X data. Xquik charges only for delivered, unique, filter-matching results and never pads rows.

Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.

Ruby SDK guide | REST API | RubyDoc | Webhooks

Trust & usage

• 51,000+ downloads of Xquik's Twitter API packages on npm, PyPI, RubyGems, NuGet, Packagist & Terraform (source)
• 7,800+ users of Xquik's Twitter scraper Actors on Apify (source)
• 5,700,000+ runs of Xquik's Twitter scraper Actors on Apify (source)
• 4.66 of 5 for the X Tweet Scraper from 16 Apify reviews (source)
• 3,900+ accounts on xquik.com (source)
• 1,600+ installs of Xquik's Twitter Skills on skills.sh (source)
• $38,000+ in revenue verified by TrustMRR (source)
• 501 ms median REST API read time over the last 7 days (source)
• 370+ GitHub stars across Xquik's repos (source)
• 9,900+ downloads of x-twitter-scraper on RubyGems (source)
• This repo meets the OpenSSF Best Practices passing criteria (source)

Checked on 2026-10-15. See each number with its date & source on xquik.com/trust or as JSON.

Common Twitter & X tasks

Task	REST route	Usage
Search tweets without the X API	GET /x/tweets/search	Use keyword or advanced operator queries.
Read an X profile timeline	GET /x/users/{id}/tweets	Paginate bounded results.
Scrape Twitter followers	GET /x/users/{id}/followers	Use an extraction for complete datasets.
Scrape following accounts	GET /x/users/{id}/following	Use an extraction for complete datasets.
Read a home timeline	GET /x/timeline	Approve this private read.
Export large X datasets	POST /extractions	Poll status, then download results.
Download or upload media	/x/media/*	Use typed file helpers.
Monitor an account	POST /monitors	Deliver events through HMAC webhooks.
Post or reply	POST /x/tweets	Confirm the account and payload.

Installation

The SDK requires Ruby 3.2.0 or later.

Add the gem to your Gemfile.

gem "x-twitter-scraper", "~> 0.10.6"

Usage

require "bundler/setup"
require "x_twitter_scraper"

x_twitter_scraper = XTwitterScraper::Client.new(
  api_key: ENV["X_TWITTER_SCRAPER_API_KEY"] # Optional. The client reads this variable.
)

response = x_twitter_scraper.x.tweets.search(q: "from:elonmusk", limit: 10)

puts(response)

Handling errors

The SDK raises an APIError subclass for connection failures and non-2xx responses.

begin
  account = x_twitter_scraper.account.retrieve
rescue XTwitterScraper::Errors::APIConnectionError => e
  puts("Could not reach the server. Check the connection.")
  puts(e.cause)  # Underlying net/http exception.
rescue XTwitterScraper::Errors::RateLimitError => e
  puts("Rate limited. Retry later.")
rescue XTwitterScraper::Errors::APIStatusError => e
  puts("Request failed. Inspect the returned HTTP status.")
  puts(e.status)
end

Cause	Error type
HTTP 400	BadRequestError
HTTP 401	AuthenticationError
HTTP 403	PermissionDeniedError
HTTP 404	NotFoundError
HTTP 409	ConflictError
HTTP 422	UnprocessableEntityError
HTTP 429	RateLimitError
HTTP >= 500	InternalServerError
Other HTTP error	APIStatusError
Timeout	APITimeoutError
Network error	APIConnectionError

Retries

The SDK retries connection errors, timeouts & HTTP 408, 409, 429, and 5xx responses. It uses exponential backoff with 2 retries by default. Set max_retries to change or disable retries.

# Change the client default.
x_twitter_scraper = XTwitterScraper::Client.new(
  max_retries: 0
)

# Override one request.
x_twitter_scraper.account.retrieve(request_options: {max_retries: 5})

Timeouts

Requests time out after 60 seconds. Set timeout to change or disable this limit.

# Change the client default.
x_twitter_scraper = XTwitterScraper::Client.new(
  timeout: nil
)

# Override one request.
x_twitter_scraper.account.retrieve(request_options: {timeout: 5})

Timeouts raise XTwitterScraper::Errors::APITimeoutError and follow the retry policy.

BaseModel

All parameter and response objects inherit from XTwitterScraper::Internal::Type::BaseModel and support these operations.

1. Access known and unknown fields with obj[:prop].
2. Destructure fields with obj => {prop: prop} or pattern matching.
3. Compare objects by their field values with ==.
4. Print classes and instances in a readable format.
5. Convert values with #to_h, #deep_to_h, #to_json, or #to_yaml.

Custom requests

Use extra_query, extra_body, or extra_headers under request_options. Matching extra_ values override documented parameters.

account =
  x_twitter_scraper.account.retrieve(
    request_options: {
      extra_query: {my_query_parameter: value},
      extra_body: {my_body_parameter: value},
      extra_headers: {"my-header": value}
    }
  )

puts(account[:my_undocumented_property])

Use client.request for undocumented endpoints. It keeps authentication and retries.

response = client.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)

Concurrency & connection pooling

Clients are thread-safe. Fork them only when no HTTP requests are in flight. Each client has an HTTP connection pool with a default size of 99. Reuse 1 client per application in most cases. Requests wait when every connection is busy. This wait counts toward the request timeout. Other SDK classes do not lock their data.

Sorbet

The gem ships RBI definitions without sorbet-runtime.

Pass request hashes or typed parameter objects.

x_twitter_scraper.x.tweets.search(q: "from:elonmusk", limit: 10)

params = XTwitterScraper::X::TweetSearchParams.new(q: "from:elonmusk", limit: 10)
x_twitter_scraper.x.tweets.search(**params)

Enums

Tagged symbols replace T::Enum and remain runtime primitives.

# :en
puts(XTwitterScraper::AccountUpdateLocaleParams::Locale::EN)

# Revealed type: `T.all(XTwitterScraper::AccountUpdateLocaleParams::Locale, Symbol)`
T.reveal_type(XTwitterScraper::AccountUpdateLocaleParams::Locale::EN)

Enum parameters accept constants or literal values.

x_twitter_scraper.account.update_locale(
  locale: XTwitterScraper::AccountUpdateLocaleParams::Locale::EN,
  # …
)

x_twitter_scraper.account.update_locale(
  locale: :en,
  # …
)

Versioning

This package follows SemVer. Version 0 releases may change APIs.

Changes to non-runtime *.rbi and *.rbs definitions are non-breaking.

More Xquik tools

• X (Twitter) scraper API & Twitter MCP server with REST, MCP & Skill setup.
• Twitter API SDKs for TypeScript, Python, Go, Java, Kotlin, C# & PHP.
• Twitter CLI & X CLI for terminal workflows.
• Twitter advanced search operators with tested examples.
• Xquik X API & Twitter scraper and the Twitter API documentation.

Help & contributing

• Report vulnerabilities through the security policy.
• Ask usage questions through the organization support policy.
• Read the contribution guide.

Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.