twitter-ruby: an API v1.1 client whose own page points you at a different gem

The gem targets v1.1 and sends new projects elsewhere

The first substantive paragraph answers a question the reader did not ask yet. This gem provides a Ruby interface to the X (Twitter) API v1.1, and for new projects, or if you need API v2 support, the page directs you to the X gem as a more modern alternative that supports both API v1.1 and API v2. That sentence is the whole adoption story. A team with a working v1.1 integration is looking at a wrapper whose methods map closely onto the endpoints it already calls, while a team starting fresh is being told twice to pick a different gem, once for new projects and once for v2. The repository is not archived and the last push to master is 2026-11-02, so the wrapper is still being touched; there are simply no GitHub releases attached to it, which means version history lives on the gem host and in CHANGELOG.md rather than in tags.

OAuth arrives as two key and secret pairs

Configuration is one block, and it is the only setup the API needs because v1.1 requests require OAuth credentials. Before writing any code you register an app in the X developer portal, and after creating it you have a consumer key and secret pair plus an access token and secret pair. Those four values are handed to the client as a block:

client = Twitter::REST::Client.new do |config|
  config.consumer_key        = "YOUR_CONSUMER_KEY"
  config.consumer_secret     = "YOUR_CONSUMER_SECRET"
  config.access_token        = "YOUR_ACCESS_TOKEN"
  config.access_token_secret = "YOUR_ACCESS_SECRET"
end

The block form rather than a hash or a config file is the design decision, because it keeps credentials in one place with the rest of your object construction and makes the client easy to build in a test with dummy values. Note what the credentials are for: they represent a user, since the access token pair is tied to an account, which is why the examples below include both authenticated actions such as posting and public lookups such as fetching a user.

Every lookup accepts a screen name or a numeric ID

The method surface is small and consistent. Identifiers are polymorphic, so a follow can be written as client.follow("gem") or client.follow(213747670), and the same pair works for fetching a user with client.user. The list methods are the clearest case, because followers and friends each take three forms: a screen name, a user ID, or nothing at all, which means the authenticated user. Both return cursored lists rather than the whole set, so paginating is part of the contract instead of an afterthought. The remaining timeline calls are single methods with no arguments, including home_timeline for the authenticated user's home feed and mentions_timeline for tweets mentioning that user, while user_timeline takes the same screen name or user ID pair, and a single tweet is fetched by its numeric identifier through client.status.

The practical consequence is that renaming an account never breaks your code path, since the numeric form is always available, but any code that assumes a list is complete will be wrong, since the cursors have to be walked.

Search takes a query string, a result type and a language

Search is where the options show up, and two examples cover most of what you need. The first narrows by result type and then takes only the first few matches:

client.search("to:justinbieber marry me", result_type: "recent").take(3).map do |tweet|
  "#{tweet.user.screen_name}: #{tweet.text}"
end

The second combines operators and a language filter, and shows the -rt prefix that excludes retweets:

client.search("#ruby -rt", lang: "ja").first.text

The README's examples use the to: prefix and the minus sign exclusion inside the query, and bound the results with take and first. Posting is the other half of the surface, a single client.update call with the text, which sends the tweet as the authenticated user.

Streaming hands you six object types, not just tweets

The streaming client covers the legacy v1.1 endpoints and is configured exactly like the REST client, with the same four credentials in a Twitter::Streaming::Client.new block. What differs is what arrives: the callbacks yield an object that may be Twitter::Tweet, Twitter::DirectMessage, Twitter::Streaming::DeletedTweet, Twitter::Streaming::Event, Twitter::Streaming::FriendList or Twitter::Streaming::StallWarning. That list is the real API contract, and the examples show why, with a case statement that handles a tweet, a direct message and a stall warning separately. Three entry points cover the usual cases: client.sample for a random sample, client.filter with a track list built from topics for keyword matching, and client.user for tweets, events and direct messages belonging to the authenticated user. The critical caveat is stated once and matters more than the method names: endpoint availability and access requirements depend on your developer account, so a correctly written stream can still be unavailable to you.

Five workflows, two linters and a signature directory

The repository layout shows how much machinery sits behind a small API. Five GitHub Actions workflows appear as badges: lint, test, mutant, typecheck and yardstick, so mutation testing and documentation coverage are both part of the loop, not extras. The type checking has real files behind it, a Steepfile and a sig/ directory of signatures, which is what a statically typed Ruby setup needs. Two linters are configured side by side with .rubocop.yml and .standard.yml, and .jrubyrc sits at the root for JRuby, which tells you the supported runtimes are not only CRuby. Documentation is generated from .yardopts, and the examples/ directory is a set of markdown files rather than scripts: AllTweets.md, Configuration.md, RateLimiting.md, Search.md, Streaming.md, Update.md and a README.

Version tracking lives on the gem host, and one paragraph names the other gem

Two small inconsistencies are useful signals about where this project sits. First, there are no GitHub releases, so a consumer pinning the gem depends on rubygems.org and on CHANGELOG.md at the repository root to learn what changed; the gem itself is published as twitter and its documentation lives at rubydoc.info/gems/twitter. Second, the sponsorship section closes with the line Together we can make the X gem even better, which names the successor project inside this gem's own repository. Copyright runs from 2006 to 2026 and lists Erik Berlin, John Nunemaker, Wynn Netherland, Steve Richert and Steve Agalloco, and the README asks readers to follow @gem on X for announcements about this library. Taken together, the picture is a long lived wrapper whose maintainers have already pointed new work at a different gem, so treat upgrade notes as the thing to read before you change a version.

Editorial conclusion

Keep twitter-ruby when you already have Ruby code calling v1.1 endpoints such as home_timeline or filter, because the call shapes stay identical and moving means rewriting against a different gem. Do not start new work on it, since the project recommends the X gem for new projects and for v2, and note that streaming availability depends on your developer account rather than on the gem.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. sferik/twitter-ruby on GitHub