API FAQ

What's an API?

The acronym "API" stands for "Application Programming Interface". An API is a defined way for a program to accomplish a task, usually by retrieving or modifying data. In Twitter's case, we provide an API method for just about every feature you can see on our website. Programmers use the Twitter API to make applications, websites, widgets, and other projects that interact with Twitter. Programs talk to the Twitter API over HTTP, the same protocol that your browser uses to visit and interact with web pages.

How do I use the Twitter API?

If you want to create an application to that will interact with the Twitter APIs you should check out the developer documentation. Many developers have created libraries that do a lot of the heavy lifting needed to interact with the APIs for you. A selection of these libraries are listed on our OAuth Libraries page. If you want to see examples of complete, working Twitter API projects, there are plenty of open source examples to look through.

How do I count out 140 characters?

Defining a "character", and then counting out 140 of them is key to any Twitter application that wishes to create Tweets. If your application will be Tweeting you will want to read our counting characters page to make sure you know how to do it. Alternatively you may wish to use other solutions for Tweeting like the Tweet Button, Web Intents and @anywhere.

What is the version of the REST API?

In the API documentation there is a version place marker in the example request URL. Currently only one version of the API exists, that version is 1. This means any REST API queries will be of the format: https://api.twitter.com/1/statuses/user_timeline.json.

How do I get “via [MyApp]” appended to updates sent from my API application?

The source attribution of a Tweet is set by the name of the application used to create it. If you register an application we will use it's name and URL as the source for any Tweet it creates. Application names must be unique so if the application name you wish to use is taken, please choose another.

I keep hitting the rate limit. How do I get more requests per hour?

REST & Search API Whitelisting is not provided. Resourceful use of more efficient REST API requests, authentication, and Streaming APIs will allow you to build your integration successfully without requiring whitelisting. Learn more about rate limits or see the rate limiting FAQ for more information.

How can I reclaim an inactive Twitter account for my project or application?

Our Inactive Account Policy page on the help center contains information about how we handle inactive accounts. For Trademark Violations please refer to our Trademark Policy.

How do I report bugs and request features?

You can see the list of existing issues on our issue tracker. Before submitting an issue or feature request you should search the list to see if it exists already. If you see a feature which you think will be of benefit to you or your users you should 'star' it. Comments in enhancements give us some context but we use the stars to help identify if it's a popular request or not.

If you see an issue which you are also experiencing you can help by contributing any information to help reproduce the problem. Any response headers and content from the API that show the error are also really helpful.

How can I get my application in the promotion box?

The promotion box is a curated list of applications recommended by Twitter staff. Opportunities to apply for promotion in this space of Twitter.com are no longer offered.

What am I doing wrong?

• The first thing to do is check the response you receive from the Twitter API when making your request. You should check the response body in addition to the HTTP Status Code. In many cases the reason for the request failing is provided in the response body.
• If the response body doesn't help identify the problem, check @twitterapi and status.twitter.com to see if there are any known issues with the API at that time.
• If you are using your own library, try using another library to see if the same issue occurs. You can find libraries for many programming languages on our OAuth Libraries page.
• If you are still seeing problems send a message to the developer mailing list where Twitter Employees and Community Developers can try and help you. Make sure you include the language you are using, the request that's failing and the response (including headers) that you get back. The more information you provide in the email the quicker somebody can help you out.
• Alternatively you may wish to join the #twitterapi IRC channel (details on http://dev.twitter.com/discuss).

Please avoid creating bug reports on the issue tracker until the developer mailing list has tried to help you first.

Why do I keep getting the wrong Tweet IDs?

See Twitter IDs, JSON and Snowflake. This is an issue with JSON parsing of large integers -- by looking at/consuming the JSON the ID value is munged. Use id_str instead of id whenever possible.

Is the Twitter API down?

The Twitter Status log and @twitterapi share information about any known issues with Twitter that could be affecting the API.

Is my IP banned or blacklisted?

Being banned or blacklisted means the Twitter APIs will not respond to requests you make to them. You know if you have been blacklisted because the APIs will not respond to you at all. If this happens to you the first thing to do is stop any requests your application is making. Then see if you can reach other URLs using a command line tool like curl. If you can access other URLs but not Twitter, you should login to Twitter.com and then file a ticket with our support team. The support team will then be in contact about next steps.

Twitter provides APIs for free and with no guarantees of service availability. This means we may take steps to ban or block any account, IP, or range of IPs that might be harming our ability to provide Twitter in a timely and reliable way.

The best way to avoid being blacklisted is to pay attention to the remaining API requests you are allowed to make, and to handle errors appropriately. Handling errors appropriately means reducing your request frequency (throttling) or stopping requests until you can identify why the request failed.

Why do my image uploads fail?

The image update methods require multipart form data. They do not accept a URL to an image nor do they accept the raw image bytes. They instead require the data to be delivered in the form of a file upload filed as defined in RFC1867. The content-type attribute of the image field is checked for valid image type. If you are using PHP/CURL there is a known bug that has since been fixed in the CVS version of PHP. Most installations are not yet using this version and therefore fail during image upload. Consider using a library which says it supports image uploads before trying to create your own.

How do I keep from running into the rate limit?

• Caching. We recommend that you cache API responses in your application or on your site if you expect high-volume usage. For example, don't try to call the Twitter API on every page load of your hugely popular website. Instead, call our API once a minute and save the response to your local server, displaying your cached version on your site. Refer to the Terms of Service for specific information about caching limitations.
• Rate limiting by active user. If your site keeps track of many Twitter users (for example, fetching their current status or statistics about their Twitter usage), please consider only requesting data for users who have recently signed in to your site.
• Scale your use of the API with the number of users you have. When using OAuth to authenticate requests with the API, the rate limit applied is specific to that user_token. This means, every user who authorizes your application to act on their behalf, has their own bucket of API requests for you to use.
• Request only what you need, and only when you need it. For example, polling the REST API looking for new data is inefficient for both your application, and the Twitter API. Instead consider using one of the Streaming APIs as a signal of when to make REST API requests.
• Consider using a combination of the APIs to achieve your goal. You can't do everything with one API, but by combining them you can do most things. For example, instead of using the Search API for all your querying, use the Streaming API to track keywords and follow users Tweets, and save the Search API for the more complex queries.

These are just some example strategies. To work out different solutions for you to achieve your goals send a message to the developer mailing list where Twitter Employees and Community Developers can help recommend things for you to try.

How can I keep up with changes to the Twitter API?

There are a number of great ways to follow the changes we make to the Twitter API:

• Follow @twitterapi.
• Keep track of our Developer Blog and Discussions.