Frequently Asked Questions

Basics

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

There are a two great ways to follow the changes we make to the Twitter platform:

• Follow @twitterapi.
• Keep track of our Developer Blog and Discussions.
• See the recently updated documentation.

How do I count out 140 characters?

While Tweets are still limited to 140 characters, the character counting model has evolved over time. Tweets are UTF-8 string content and any UTF-8 character counts as a single character. Strings that are understood as links, such as "http://twitter.com", "twitter.com", "twitter.com/twitterapi" will be automatically converted to t.co. t.co links represent a variant character count (currently "20" for HTTP-based links and "21" for HTTPS-based links). See How Twitter wraps URLs with t.co for more information on how t.co plays a role in character counting. Counting Characters provides more details on character counting strategies.

How do I obtain an API key?

You can create an application record (which includes an API key) by navigating to Application Management.

Most integrations with the API will require you to identify your application to Twitter by way of an API key. On the Twitter platform, the term "API key" usually refers to what's called an OAuth consumer key. This string identifies your application when making requests to the API. In OAuth 1.0a, your "API keys" might refer to the combination of this consumer key and the "consumer secret," a string that used to securely "sign" your requests to Twitter. Most requests to Twitter require a user context in addition to the application context. User context is presented through the use of another kind of token/key called the "access token." See Obtaining access tokens for more information.

How do I properly navigate a timeline?

The Working with Timelines document describes the optimal way to obtain tweets from timelines such as GET statuses/home_timeline, GET statuses/mentions and GET statuses/user_timeline.

The "count" parameter behaves more closely in concept to an "up to" parameter in that you'll receive up to the number specified in the parameter. You cannot be guaranteed that you'll receive the total amount you've requested, even if the timeline contains at least that many accessible tweets. Parameters such as include_retweets=true and exclude_replies=true effect the number of results timeline methods will yield per request.

There are no explicit methods to walk timelines by date or time. Use since_id and max_id to consume a timeline linearly.

How do I use the REST API over JSON-P?

The REST API supports a callback parameter on nearly all methods. See Things Every Developer Should Know for more information.

How do I use the Twitter platform?

Twitter offers a platform with a number of different ways to interact with it.

Web Intents, Tweet Button and Follow Button is the simplest way to bring basic Twitter functionality to your site. It provides features like the ability to tweet, retweet, or follow using basic HTML and Javascript. You can also embed individual tweets.

More complex integrations can utilize our REST, Search, and Streaming APIs. The Streaming API allows you to stream tweets in real time as they happen. The Search API provides relevant results to ad-hoc user queries from a limited corpus of recent tweets. The REST API allows access to the nouns and verbs of Twitter such as reading timelines, tweeting, and following.

To use the REST and Streaming API, you should register an application and get to know the ways of OAuth and explore Twitter Libraries.

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. The Streaming API is currently on version 1 as well, while the Search API is unversioned.

What kind of data can I get from the API?

To explore the kind of data available to you in the API, browse the available resources and this field guide to the most commonly accessed platform objects.

What kind of data does the Twitter Platform capture?

Like many companies, Twitter receives log data from visits to websites that use our social widgets, such as our Tweet and Follow buttons. This log data may include information such as IP address, browser type, the referring web page, pages visited, cookies, and other interactions with the buttons or widgets as outlined in our privacy policy: https://twitter.com/privacy

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.

What's the difference between User Streams and Site Streams?

User streams provides a way for a single user to be streamed the equivalent of their home timeline (the tweets authored by the users they follow) and mentions timeline (the tweets authored by users @mentioning that user). It also offers the ability to be streamed DMs received by the user when permissioned. In addition to those data points, events like other users favoriting or retweeting that user's tweets, users following that user (or that user following other users), and so on.

Think of it as a "me feed" -- everything about Twitter the service as it relates to "me" the account holder. TweetDeck, Twitter for Mac, and Tweetbot for iPad all use User Streams to stream these tweets and related events about a single user in real-time.

Site streams is an expansion of this concept for services that want to stream the equivalent of this "me feed" on behalf of many users at a time. This makes Site Streams appropriate for web sites and services that act on behalf of many mutual users in a centralized fashion. User Streams is more appropriate for a single-user client-side application or a very limited server scenario while developing a bot that responds to DMs, for example.

User Streams also allows a user to track a limited amount of real-time "searches" on public tweets, mixed in with the "me feed." Site Streams does not offer this ability directly.

Why are embedded objects stale or inaccurate?

It's best to go to the primary resource for a definitive "answer" about something. Information about tweets should come from methods in the statuses namespace. Information about users from the users namespace. Information about following relationships in the friends/followings/followers/friendships namespaces and so on.

When calling a method without authentication, there is no user context/agency to determine whether the "current user" is following the user embedded within the status. In those cases the typically boolean field is neither true nor false, but null.

The Twitter API has been around for awhile now. We're still on version 1, but we've got to make up for decisions made years ago while maintaining overall compatibility. One early decision made on the API was to include what's called perspectival attributes embedded within a child object of an unlike parent object. For example, tweets are the parent object, users are the child object, and whether the current user making the request is following that child user object or not is the perspectival "following" attribute. As the service has grown, these kind of inner values have become harder to maintain at scale.

When you make the request using authentication, we make a best effort to return to you a accurate, up to date, and perspectivally-contextual response, starting with the primary object in the highest priority and diminishing from there. If we can't determine the following status in a timely fashion (due to having to make rapid calculations while serving the caller the object), we'll respond with "null" rater than "true" or "false" because the status is indeterminate.

Authentication & Rate Limiting

Do Twitter's OAuth 1.0A access tokens expire?

The access tokens yielded to your through the OAuth process do not have an explicit expiration datetime attached to them. They will be valid for use when making requests on behalf of your users for as long as the user has granted your application access. A user can revoke access to your application at any time.

Please note that the strings representing access tokens are not static -- if a user revokes your application or otherwise transits from one permission level to another (such as from read-only to read-write), the strings will be altered.

How are rate limits determined on the Streaming API?

The public streaming APIs cap the number of messages sent to your client to a small fraction of the total volume of Tweets at any given moment.

The sample hose, as documented in https://stream.twitter.com/1/statuses/sample.json, delivers a random sampling of all Tweets at a volume equal to the public streaming cap.

Filtered streams return all matching Tweets up to a volume equal to the streaming cap. If there are more tweets that would match your criteria, you'll be streamed a rate limit message indicating how many tweets were not delivered.

How do I get access tokens from my iOS5 native Twitter application to my server?

Using Reverse Auth is a method of converting the access representations available in the iOS Twitter framework. Usage of this API requires permission from Twitter's API policy team. Send a request to api@twitter.com with plenty of details about your application and why Reverse Auth is the best choice for it.

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, search through discussions on the topic or start your own.

How do I obtain a user's email address?

If you'd like a user's email address, you'll need to ask a user for it within the confines of your own application and service. The Twitter API does not provide the user's email address as part of the OAuth token negotiation process nor does it offer other means to obtain it.

How do password resets effect application authorization?

When using OAuth, application connectivity and permissions do not change when a user resets their password on twitter.com. The relationship between Twitter, a user, and a third-party application do not involve a username and password combination. When a Twitter user changes their password, we'll now ask the user whether they would also like to revoke any of their application authorizations, but any revocations are manually executed by the end user.

As of March 12, 2012 it is still possible to connect to the The Streaming APIs via Basic Auth credentials. If the password belonging to a user account that connects to the Streaming API via basic auth is changed, the new password will need to be used to regain that connection.

How long do I have to wait when requesting xAuth?

Most xAuth requests will be processed within 72 business day hours though there are times of increased demand which can extend this duration. Plan accordingly and be sure that your initial request for xAuth access contains everything an API Policy Team member would need to confirm the legitimacy of the request and your readiness for the feature.

I don't want to require users to authenticate but 150 requests per hour is not enough for my app, what should I do?

Rethink not wanting to require authentication. It's the primary means to grow your application's capabilities. We recommend requiring authentication to make use of potentially 350 requests per hour per access token/user. Consider also investigating whether the Streaming API's follow filter will work for you.

I set my app to "read, write, and direct messages" but it still won't let me read my direct messages; why?

Permissions set at the application level are effective only for access tokens generated after the requested permission level is set. If you generated an access token while the permission level was still set to read-only or just read & write, you'll need to renegotiate the access token through the OAuth flow for the access token to hold the upgraded permissions.

Changes to permission settings can take a few minutes to apply.

What consequences are there to resetting my consumer key and secret?

If your consumer key and secret become compromised for any reason, you may need to reset it to regain secure control of your application's identity and the actions taken in its name. Resetting your consumer key does not reset the strings representing your users (their "access tokens") but does make your access tokens invalid when used with the former key. When your existent access tokens are used with your new consumer key and secret, they will continue functioning as expected. Your new consumer key and secret will be represented by completely different strings than its previous incarnation.

What's a placeholder URL? How do I set my callback URL?

In OAuth 1.0a, you're required to send an explicit oauth_callback value on every request to POST oauth/request_token, regardless of any pre-registered callback you may have associated with your application or if you're going to be performing out-of-band OAuth (for which you'd provide an oauth_callback=oob value).

When you create or edit your application on dev.twitter.com, you need to choose which kind of OAuth authentication you'll be using: standard callback-based OAuth, out-of-band mode OAuth (also known as "PIN-code OAuth" & "OOB OAuth"), or xAuth.

If you're exclusively using out-of-band OAuth or xAuth, you want to leave the "Callback URL" field empty. By doing so, your application will not allow for callback-based OAuth to be performed.

If you'll be using callback-based OAuth, you want to provide the "Callback URL" field with a fully qualified "placeholder" URL. This URL does not have to be the actual oauth_callback value you'll send on oauth/request_token, but it does need to represent a HTTP or HTTPS-based URL with a TLD we recognize. If you know you'll be performing callback-based OAuth, consider just providing a URL to your home page.

You can provide non-standard URI types to oauth/request_token with a dynamic oauth_callback parameter but cannot use such schemes on your application record.

Application Management

How do I allow additional users to maintain my application record?

This is not supported at this time and only one user account can maintain an application record. It's recommended to ensure that applications belong to accounts that are directly in an organization or developer's control. See How do I transfer my application to another account? if it is necessary for you to transfer ownership.

How do I transfer my application to another account?

To get the process started, email api@twitter.com from the email address associated with the account currently owning the application. Include the @username you want to become the owner once the process is complete and any other explanation you may think is necessary. It can take a few days to process.

Finding & Counting Things

How do I count favorites?

Favorite counts aren't available as part of tweet objects in the REST, Streaming or Search APIs at this time. User streams and Site streams both stream events when an authenticated user favorites tweets or has their tweets favorited. Using these authenticated streaming APIs, you can count favorites in real-time as they happen. This is currently the only scalable means to count favorite activity.

How do I count retweets?

Tweets in the REST and Streaming APIs contain a field called retweet_count that provides the number of times that tweet has been retweeted. You can obtain the retweet count for any arbitrary tweet by using GET statuses/show/:id.

You can count retweets as they happen by using a The Streaming APIs. In particular, User streams and Site streams allow you to be streamed retweet events about/around an authenticated user in real time.

Which timezone is used on date fields within Tweets and other Twitter data?

The created_at field of Tweets and other objects on Twitter are stored in UTC/coordinated universal time, see http://en.wikipedia.org/wiki/Coordinated_Universal_Time for more information.

The oauth_timestamp field used in OAuth 1.0A requests is in UTC-based epoch time in seconds. See http://en.wikipedia.org/wiki/Unix_time for more information.

You can find the current time as understood by Twitter's servers by examining the Date HTTP header in every API response.

Tweeting

How do I disable t.co when creating a Tweet containing a link?

There is no way to disable t.co. Links are wrapped with t.co to protect users no matter where they are interacting with Tweets. t.co is designed to be mostly transparent to the end-user through the use of Tweet Entities when rendering tweets, and the original domain will be displayed. See the t.co FAQ in our support center for more general information about t.co and then learn How Twitter wraps URLs with t.co.

Why do Tweets starting with D or M return a valid API response but not show up in my timeline?

As described in Official Twitter Text Commands, Twitter's SMS interface allows for sending direct messages by using either of these formats:

D <username> <text>
M <username> <text>

These are valid anywhere you can issue a Tweet - try sending a DM through the Tweet box on twitter.com, for example. Unfortunately, this means that you cannot issue a public Tweet starting with either letter - it will be treated as a DM to the user whose screen name matches the second word in the Tweet.

Responses to statuses/update when using these commands will return the most recent tweet rather than a sent direct message.

Why won't statuses/update let me post a link to a specific domain name?

Some domain names get identified as spam or malware. If you believe that you should be able to validly use a domain name, see this support article for further instructions: My Website is Being Flagged as Malware or Spam! and email tcoabuse@twitter.com with details about your domain.

Advertising

Is there an Advertising API for posting ads to Twitter?

As of March 12th, 2012 there is not yet an API allowing an advertiser to create or manage Promoted Products campaigns on Twitter. For updates on advertising with Twitter, follow the Twitter Advertising Blog: http://advertising.twitter.com

Is there an Advertising API for serving Twitter ads in my third party application?

As of March 12, 2012 there is no Advertising API for serving Twitter's promoted products in third party applications.

What guidelines are there for using Twitter content (such as Tweets) in advertising campaigns?

The Developer Rules of the Road, section IV, part 3 describes the current rules around using Twitter content within advertising.

Troubleshooting

How do I contest an application suspension?

See How To Appeal an Application Suspension from our support center.

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.

If you believe your IP address is blocked for some reason, contact API Policy at api@twitter.com with as much detail as possible.

Is the Twitter API down? Where can I find information about platform health?

The API status page should be the first place you check for this information. There you will find information about average latency, known issues, and occaisionally information about transient service states.

Additionally, you can follow @twitterapi for tweets about service health, new features, and more.

Finally, the Twitter Status blog at http://status.twitter.com shares information about service-wide issues that may also effect the platform.

What am I doing wrong?

Troubleshooting with the API is usually done with these steps:

• Examine the HTTP response closely: the status code you received back, the message that accompanies that code, the HTTP headers in the response, and the response body itself -- the response body usually contains the most specific information about the nature of an error.
• If you're using OAuth but the response doesn't seem like what you're expecting, look for an X-Warning HTTP header that informs you that your OAuth is invalid. We will often service invalid requests as if OAuth were not sent at all rather than rejecting it.
• Consult Troubleshooting OAuth 1.0A for tips on troubleshooting OAuth problems.
• If the response body doesn't help identify the problem, check @twitterapi and https://status.twitter.com or API Status 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 or curl to see if the same issue occurs. You can find libraries for many programming languages on our Twitter Libraries page.
• If you are still seeing problems send a message Discussions 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.

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

What does HTTP status code 0 mean?

If you're making requests to the Twitter platform and receive an HTTP status code "0," it means that the request never made it to our servers. Investigate whether your HTTP library, programming language, system environment, network and/or proxies are configured to allow traffic over HTTP and HTTPS to the endpoints you will be using.

Why are the Tweets I'm looking for not in Twitter Search, the Search API, or Search widgets?

Twitter's search is optimized to serve relevant tweets to end-users in response to direct, non-recurring queries such as #hashtags, URLs, domains, and keywords. The Search API (which also powers Twitter's search widget) is an interface to this search engine. Our search service is not meant to be an exhaustive archive of public tweets and not all tweets are indexed or returned. Some results are refined to better combat spam and increase relevance. Due to capacity constraints, the index currently only covers about a week's worth of tweets.

The user timeline API is the definitive source of tweets by a specific author. For a collection of recent Tweets by more than one user, consider creating a Twitter List and leveraging the list timeline. The Streaming API is often the best-fit choice when seeking completeness.

If the tweets you're looking for aren't available in search and you think they should be, consult this support topic for further instructions to contact @Support.

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.

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.

Getting help

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 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.

How do I get my account verified?

This site is focused on programmatic uses of the Twitter Platform. We do not review nor approve any requests for the closed account verification program. Please do not use this site to request verification. If you have any questions about verification, see FAQs about Verification and reach out to @Support via DM if you have any questions.

How do I get support for my account, the Twitter website, or Twitter for my mobile device?

The Twitter Help Center is the ideal location for getting support with your Twitter account, the Twitter website, or Twitter for your mobile device. If you have feature requests, ideas, or complaints about the Twitter service, you should direct them via DM to @support or use the forms available to you on the Help Center. We can't help with general product support issues on dev.twitter.com.

How do I link my Facebook and Twitter accounts?

We can't help with questions about the Twitter service link with Facebook here. If you're having issues, please read these articles and contact @Support if necessary.

• I'm having trouble using Twitter with Facebook
• How to use Twitter and Facebook

How do I report bugs and request features?

Before filing an issue to report a bug or request a feature, please:

1. Check the Issue Tracker for similar issues or requests. If you find what you're looking for, subscribe to the issue to indicate your interest.
2. Search the Discussions for similar issues and requests. If you find an active topic about the issue, use that thread to continue discussing it.
3. If you can't find your issue in either the tracker or in discussions, consider starting a discussion topic instead of creating a new issue. By creating a discussion topic, Twitter employees and third party developers can discuss the problems you're having and rule out any already-known issues, common developer error, issues with Twitter the service (as opposed to the API) or other instant resolutions to your potential issue.
4. If you're absolutely sure that what you're filing is a material issue with the platform, file an issue with as exhaustive detail as possible to reproduce your problem. Insufficiently described issues will be closed in favor of the reporter opening a discussion to further refine the issue description. Make sure to include the exact URLs you're executing, the exact POST bodies & HTTP headers you're sending and any other relevant details. When reporting an issue with OAuth, include a signature base string as well. Refrain from ever submitting your consumer secret.

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.

I want to partner with Twitter; how do I reach the business development team?

Our business development team is small and selective in the partnerships they pursue. If you're interested in partnering with Twitter, send a detailed email to partner@twitter.com -- due to volume of requests, we can't respond to all inquiries.

For many, the best path forward is to build integrations that do not require special circumstances from Twitter. The platform is multi-faceted and most product features can be accomplished through creativity and careful consideration of the technological options made available. Consider exploring the options made available by Partner Providers of Twitter Data.

What do I do if my account is compromised, hacked, or used outside of my control?

If you're having any questions about the security of your account, please contact @Support through our Support Center at https://support.twitter.com/forms/hacked -- we cannot assist with account issues on this site.

See My Account is Compromised/Hacked and I Can't Log In! and How to Connect and Revoke Third Party Applications for more helpful advice.