# twitter-ruby: a Ruby client for the X (Twitter) API v1.1

> sferik/twitter-ruby wraps the X (Twitter) API v1.1 in a Ruby client for REST calls and legacy streaming endpoints. The README points new projects at the X gem instead, which is the main thing to weigh before adopting it.

**sferik/twitter-ruby** — A Ruby interface to the Twitter API.

- Repository: https://github.com/sferik/twitter-ruby
- Website: http://www.rubydoc.info/gems/twitter
- Stars: 4,570 · Forks: 1,272
- Language: Ruby
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/sferik-twitter-ruby

## What twitter-ruby covers, and who it is still for

The gem describes itself as a Ruby interface to the X (Twitter) API v1.1. That version number is the whole scope. Every REST method in the README, from posting a tweet to fetching a cursored follower list, targets v1.1, and the streaming clients wrap legacy v1.1 streaming endpoints. The README states plainly that endpoint availability and access requirements depend on your developer account, which is a polite way of saying the gem cannot promise the endpoints will answer.

So the audience is narrow and mostly historical: Ruby codebases written against v1.1 that still have working OAuth credentials, and people maintaining scripts around those endpoints. If you are starting fresh, the README's own advice is to use the X gem, which supports both API v1.1 and API v2. A library whose own documentation redirects new users elsewhere is telling you something about where the effort goes.

## How the REST and streaming clients are put together

There are two client classes. Twitter::REST::Client handles request/response calls: update, follow, user, followers, friends, user_timeline, home_timeline, mentions_timeline, status and search. Twitter::Streaming::Client handles long-lived connections: sample, filter and user. Both take the same four OAuth values in a configuration block, so credential handling is identical across the two.

The streaming side is where the design gets interesting. A stream yields heterogeneous objects rather than a single type, and the README lists the possibilities: Twitter::Tweet, Twitter::DirectMessage, Twitter::Streaming::DeletedTweet, Twitter::Streaming::Event, Twitter::Streaming::FriendList and Twitter::Streaming::StallWarning. That last one matters. A stream that falls behind emits a stall warning instead of silently dropping data, and the README's own example prints "Falling behind!" when it arrives. Any consumer of client.user has to branch on object class, because a direct message and a deletion event arrive through the same block as ordinary tweets.

The repository layout backs this up. There are separate lib/, sig/ and test/ directories, plus a Steepfile and a .mutant.yml, so the project runs type checking and mutation testing alongside its RSpec suite. The CI badges in the README cover lint, test, mutant, typecheck and yardstick. That is a heavier verification setup than most gems of this age carry.

## Installing the gem and posting your first tweet

The README points to rubygems.org for the package and to the X developer portal for credentials. You need to register an app there first, because v1.1 requests require OAuth. After creating the app you get a consumer key/secret pair and an access token/secret pair.

Configuration is passed as a block to Twitter::REST::Client.new. The README gives exactly this form:

```ruby
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
```

With that client in hand, posting is one call. This is the README's own example:

```ruby
client.update("I'm tweeting with @gem!")
```

If the credentials are valid and the account can still reach v1.1, the tweet appears on the authenticated user's timeline. Reading works the same way, by screen name or numeric user ID:

```ruby
client.user("gem")
client.user(213747670)
```

Search is worth one look because the README shows its query syntax rather than hiding it. This finds Japanese-language tweets tagged #ruby, excluding retweets:

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

For streaming, swap the class and keep the same four config keys, then pass a block to client.sample or client.filter. The examples/ directory in the repository carries longer walkthroughs for configuration, rate limiting, search, streaming and updates.

## The v1.1 ceiling is the real limitation

The gem does not support API v2. That is not an inference; the README says so and names the X gem as the alternative that covers both versions. If your integration needs v2 endpoints, this library cannot reach them, and no configuration block will change that.

Streaming carries a second constraint. The README notes that endpoint availability and access requirements depend on your developer account, which means a working sample or filter stream is a function of your account tier, not of the gem. Code that ran last year may fail to connect today for reasons that have nothing to do with your Ruby.

The third limitation is structural: the gem is a thin wrapper. It maps Ruby method names onto v1.1 endpoints and hands back typed objects. It does not smooth over rate limits, retry failed calls, or queue writes. There is an examples/RateLimiting.md in the repository, which tells you rate limiting is something you handle in your own code rather than something the client does for you. If you want a library that manages backoff and pagination for you, this is not that library.

## twitter-ruby versus the X gem

The honest comparison here is not against some third-party client, because the README makes it for you. The X gem, by the same author, supports both API v1.1 and API v2. The difference in approach is version coverage: twitter-ruby speaks one API version, the X gem speaks two, and the newer one is the path the author recommends for new projects.

That leaves twitter-ruby in an unusual position. It is not abandoned in the sense of being archived, and the repository's CI still runs lint, test, mutant, typecheck and yardstick checks. But the documentation frames it as the older option. Choosing it means choosing to stay on v1.1 deliberately, usually because existing code already depends on those method names and object types, and a migration to the X gem would touch every call site. If you have no such code, the comparison resolves immediately in favor of the newer gem.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-22. The README carries a sponsorship section asking for monthly donations to maintain the library, add features and answer issues faster, with sponsors getting priority support and a say in the roadmap. That is a candid signal about how the work is funded: this is a volunteer-maintained gem that would like to be better funded, not a product with a support contract.

The licence is MIT, stated in the repository metadata and referenced from LICENSE.md in the README's copyright section, which credits Erik Berlin, John Nunemaker, Wynn Netherland, Steve Richert and Steve Agalloco for 2006-2026. MIT is permissive, so the practical implication is that you can vendor, modify and ship the gem inside your own application. It does not obligate the maintainers to fix anything, and it does not give you a support channel. For legal questions about your own redistribution, talk to a lawyer rather than reading a licence summary.

Upgrade cost is the sharper issue. The gem's own recommendation is to move to the X gem for v2 support, and that migration is not a version bump. Method names, configuration and the streaming object types you branch on are the surfaces that would change. Budget for touching every call site, not for changing a Gemfile line.

## Conclusion

Adopt twitter-ruby only if you already have OAuth credentials for API v1.1 and code or tooling that depends on those endpoints; the README itself recommends the X gem for new projects or anything needing API v2. It is the wrong choice for a greenfield integration, since the same author maintains the replacement. Before committing, confirm that your developer account can still reach the v1.1 REST and streaming endpoints you plan to call, and that your app's consumer key, consumer secret, access token and access token secret are issued and active.

## FAQ

### Does twitter-ruby support the X (Twitter) API v2?

No. The README states that the gem provides an interface to the X (Twitter) API v1.1, and it directs anyone who needs API v2 support to the X gem instead.

### What credentials does twitter-ruby need before it can make requests?

Twitter API v1.1 requests require OAuth, so you register an app in the X developer portal first. That gives you a consumer key/secret pair and an access token/secret pair, which the README passes to Twitter::REST::Client.new as a configuration block.

### How does twitter-ruby handle streaming objects?

The streaming client yields objects that may be Twitter::Tweet, Twitter::DirectMessage, Twitter::Streaming::DeletedTweet, Twitter::Streaming::Event, Twitter::Streaming::FriendList or Twitter::Streaming::StallWarning. The README's example branches on the object class inside the block, and warns "Falling behind!" when a stall warning arrives.

## Sources

- [Issues](https://github.com/sferik/twitter-ruby/issues)
- [License: MIT](https://github.com/sferik/twitter-ruby/blob/master/LICENSE)
- [Project website](http://www.rubydoc.info/gems/twitter)
- [README](https://github.com/sferik/twitter-ruby/blob/master/README.md)
- [sferik/twitter-ruby on GitHub](https://github.com/sferik/twitter-ruby)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sferik-twitter-ruby