How to use twurl to quickly test the Twitter API

Have you ever needed to quickly try out a query against the Twitter API? Well then... meet twurl.

The Swiss Army Knife for the Twitter APIs

I 💙 twurl. It’s an Open Source, command-line tool (written in Ruby) that enables you to quickly poke the Twitter API for data, and try out query syntax. I use it daily to verify bug reports, to help to validate test cases submitted via our developer forums, or help to answer questions posted on the twitter tag on Stack Overflow.

Why is it called “twurl”? Simple - it’s a bit like curl, for the Twitter API! 🤓

Using twurl, you can test individual endpoints and queries, and check for responses. Since it is a command-line tool, you can chain it with a handy JSON utilities like jq. jq lets you quickly format JSON documents and API responses in a pretty manner, and query or reformat them. Oh, and of course, it is really handy for scripting 📄 You can find more information on the website, including a lot of examples of how to use it effectively.

One thing to note here is that because jq has some issues with large integers, it will mangle the numeric long integer IDs inside Tweet objects, so you should always use the _str variants instead.

Getting started

The first thing you’ll need is a working Ruby interpreter installed. On my own Mac, I'm using recent Ruby installed via rvm (which I've historically preferred to rbenv, but I recognise both are useful version and install managers); on Linux installs, there's a good chance that Ruby is pre-installed, but if not, your package manager can probably help you; on Windows, you are likely to be able use RubyInstaller.

The other thing you will need to do is to register for a Twitter Developer Account, and then create a Twitter app in your dashboard to get going. Once you've done that, you will need to get your Consumer API Key and API Secret from the Details->Keys and tokens tab for the app. There's no need to generate Access Key and Secret on the dashboard, as you will be authorizing your app in the following steps.

Next steps

$ gem install twurl

Once your twurl gem is installed, you should find that running the twurl command line presents the help information (confirm via which twurl).

Good! we're making a start. Now let's authorize to Twitter. You can use twurl -T to invoke the tutorial, twurl -h for a list of options, or you can go ahead with the full twurl authorize syntax and provide your Consumer API Key and API Secret.

Ready?

Once authorized, here are a few simple commands you can try out.

Get @jack's first Tweet:

$ twurl "/1.1/statuses/show/20.json"

Get @twitterdev's user profile:

$ twurl "/1.1/users/show.json?screen_name=twitterdev"

Tip! don't get caught out by your shell. In the second case, I used a URL parameter with ?param1= syntax. If I had not added double quotes around the whole URL, my shell (zsh, in my case) would have responded with zsh: no matches found. It gets worse if you include additional URL parameters with the &param2= syntax, as the & will background the command, in many shells. If in doubt, add quotes!

Post a Tweet:

$ twurl -X POST "/1.1/statuses/update.json?status=this is a new Tweet sent using twurl"

Get a Tweet with poll from the Labs endpoint:

If you have enrolled to test the new Twitter Developer Labs APIs, you can use twurl to test them, too. Here's an example fetching a recent Tweet with a poll, requesting detailed information and expanding the poll data and author user object.

$ twurl "/labs/1/tweets?ids=1155833627743272960&format=detailed&expansions=author_id,attachments.poll_ids"

Remember that if you want to pretty print the results, you can do something like piping the output to jq.

Want to learn more?

If you enjoy learning from examples, you’ll find a Gist with a bunch of handy twurl queries here, to give you a feel for how powerful it is.

There are also instructions on how to use twurl with the Twitter Ads API (note that the Ads API requires your developer account to have additional whitelisting); and our friend Sam Schmir has his own nice tutorial on Medium, again more oriented to the Ads API, but there are some useful tips in there as well.

Let me know if you have any questions!