Frequently Asked Questions

Basics

Did something change?

The Twitter platform is constantly evolving and there is frequent change. If you have an integration that's no longer working, be sure and review the developer blog, platform calendar, recent tweets by the @twitterapi account, the API status dashboard, recently updated documentation and Twitter's status blog at http://status.twitter.com

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

There are a few 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.
• Consult the Platform Calendar.

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 "22" for HTTP-based links and "23" 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.

Use GET help/configuration to programmatically keep track of t.co wrapping lengths. The fields "short_url_length" and "short_url_length_https" will indicate the current lengths.

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" probably refer to the combination of this consumer key and the "consumer secret," a string that is 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.

Some Twitter API methods allow the use of Application-only authentication — in this context, your consumer key and secret are used to obtain what's called a "bearer token" that represents your application.

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

In API v1.1 all requests require authentication. Because of this, most JSON-P use cases are actively discouraged as it is rarely possible to perform without exposing your client credentials.

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 does the retirement of API v1 entail?

API v1 is currently set to retire on June 11, 2013. After retirement (and during the blackout tests leading up to retirement), you can expect the following:

• Authenticated & unauthenticated requests to api.twitter.com/1/* will receive HTTP 410 Gone. Use API v1.1 instead.
• Requests to search.twitter.com/search.* will receive HTTP 410 Gone. Use GET search/tweets instead.
• Requests to api.twitter.com/1/statuses/oembed.* will continue to be serviced. However, we strongly encourage developers to tolerate HTTP redirects if continuing to use this endpoint.
• Basic Auth will be disabled on stream.twitter.com/* for all users in non-elevated Streaming API roles. Such requests will receive a HTTP 401 Unauthorized. We strongly recommend all Streaming API users, including those in elevated roles, to migrate to OAuth 1.0A now.
• Requests to Streaming API paths with versions other than "1.1" (such as stream.twitter.com/1/statuses/filter.json) are deprecated — but will not be retired at this phase. We strongly recommend you move to 1.1-era Streaming API paths now.
• API v1.1 is documented as SSL-only. Make sure you're using SSL and verifying peers — see this guide for more information. Non-SSL requests will eventually be rejected.
• Legacy widgets (AKA "Goodie" or "Join the Conversation" widgets) will no longer populate with Tweets.
• JSON is API v1.1's only output format. XML, RSS, and ATOM response formats will be retired along with API v1.

What is the version of the REST API?

There are currently two active versions of the Twitter REST API.

REST API version 1.1 is the most recent version of the API. To unifying versioning across the platform, version 1.1 also encompasses the Search and Streaming APIs.

REST API version 1 is now deprecated and will cease functioning in June 2013. Move to version 1.1 as soon as possible. The concept of "version 1" of the API includes unversioned APIs like the Search API.

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 iOS native Twitter application to my server?

Using Reverse Auth is a method of converting the access representations available in the Integrating with Twitter on iOS.

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.

Why can I successfully make GET REST API requests but not POSTs?

If you've managed to get OAuth 1.0A signing working for GET-based requests but are finding that it's more difficult to make POST requests, such as to POST statuses/update, there are a few things to investigate first:

1. Only applications and access tokens with read-write permissions or above can send POST requests. Make sure that both the application and the access token you're working with have write permissions. Typically you'll receive a HTTP 403 if you've made an authorized but not permissioned request to a POST endpoint. See The Application Permission Model for more information.
2. POST requests have some special properties in OAuth 1.0A. Make sure you're using the right HTTP method in your signature base string. Make sure that your POST body is explciitly declared as Content-Type "application/x-www-form-urlencoded"
3. Make sure your POST body and query string are properly encoded. Space characters should be encoded as "%20" and most non-alphanumeric characters must also be percent encoded. Refer to this RFC for more info on http://tools.ietf.org/html/rfc3986#section-2

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 begin the process fill out the form at https://support.twitter.com/forms/platform by selecting the "I need to transfer an API key to another account" option. Be sure and provide 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?

The number of times a tweet was favorited is now available as part of tweet objects in the REST, Streaming, and Search APIs -- you'll find it presented in the "favorite_count" field.

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

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.

How do I identify and work with retweets?

In v1.1 APIs, retweeted tweets are expressed through nested objects. If you encounter a tweet object that contains a retweeted_status node, the tweet represents a retweet. The embedded retweeted_status is the tweet that has been retweeted and the outer object represents the retweet event itself.

Both objects may have duplicative fields with duplicative content, but when considering data around the original tweet that was retweeted, values from the retweeted_status object should be used.

When looking for count values like favorite_count and retweet_count, use the values from the retweeted_status. When looking for the original tweet text, use the values from retweeted_status. When looking for the original Tweet author, use the values from retweeted_status.

The only fields typically used in the outermost object are the ID, user information about the retweeter, and the created_at date for the retweet event.

While it is possible for a user to retweet or favorite a retweet (that is, the outer-most object instead of the retweeted_status), the end result object created will be another retweet of the original status.

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 contact support through https://support.twitter.com/forms/spam with details about your domain.

Advertising

Is there an Advertising API for posting ads to Twitter?

Twitter has announced it's Ads API on February 20th, 2013 - https://blog.twitter.com/2013/announcing-twitter-ads-api. If you are interested in integrating the Twitter Ads API please review the Twitter Ads API program for details and conditions to apply - https://dev.twitter.com/programs/ads-api. 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

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.

Where can I find help with accessing my Twitter Archive?

Please read How to download your Twitter Archive in our help center for more information on retrieving your Twitter Archive.

If you're having trouble opening, viewing, or accessing your downloaded archive, please take note of your web browser, version, and operating system and file a support ticket through https://support.twitter.com/forms/general?subtopic=twitter_archive

Why am I getting a HTTP 404 for my timeline feed?

If you're requesting a timeline URL that used to work but now does not, you are likely using an outdated URL that has been retired. In March of 2012 we announced that "unversioned endpoints," GET statuses/public_timeline, and the v1 REST ATOM response format were deprecated and would eventually cease functioning. In early October 2012, we turned off these endpoints.

You can identify unversioned endpoints by examining their URL: http://twitter.com/statuses/user_timeline/twitterapi.rss is missing both the API version and the "api" subdomain. The correct URL for the same request would be https://api.twitter.com/1/statuses/user_timeline.rss?screen_name=twitterapi

Please note that there is no support for the RSS response format in API v1.1. Properly versioned API v1 URLs will cease functioning in March 2013.

For help dealing with the Spring 2012 deprecations, see Following up on API housekeeping.

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 deactivate an account?

Deactivating accounts cannot be accomplished with the API. Please read How to Deactivate Your Account on our support site for information about deactivating your account.

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.

All verification requests on this site are subject to deletion.

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 Twitter Certified Products Program.

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.

REST API v1.1

Does the Search API require authentication?

Yes, GET search/tweets requires some form of authentication -- as does the entire v1.1 REST API. Depending on your use case, you can use Application-only authentication or OAuth 1.0A to issue queries. Also consider using Embedded Timelines.

How should we handle @usernames?

When cross-posting to Twitter with @usernames, be sure to accurately map to the user the author intended to @mention. If your service binds users' Twitter accounts with its own concept of a user profiles, then you can use these relationships to help cross-post @usernames accurately. In cases where these relationships don't exist or your application can't map to the correct Twitter user, we recommend cross-posting with either users' real names or their username without the "@" symbol pre-fixed.

I'm a teapot, how does API v1.1 affect me?

418. #nuffsaid

I'm a user, how does API v1.1 affect me?

There should not be any major impact for users.

What happens to the widgets that are based on the Search API and API version 1.0?

They will be deprecated when version 1 is closed. We recommend using the new Embedded Timelines instead.

What output formats will API v1.1 support?

API v1.1 will support JSON only. We’ve been hinting at this for some time now, first dropping XML support on the Streaming API and more recently on the trends API. XML, Atom, and RSS are infrequently used today, and we’ve chosen to throw our support behind the JSON format shared across the platform. Consequently, we’ve decided to discontinue support for these other formats. For historical context, when we originally built the API all major languages did not have performant, well vetted libraries supporting JSON - today they do.

When will API 1.0 be retired?

We will begin to temporarily turn off the endpoints for API v1.0 starting March 5th, 2013 for a series of "blackout tests". See Planning for API v1’s Retirement for more information. Final retirement is currently scheduled for June 11, 2013.

Will an application have to request user authorization just to make public API calls?

When API v1.1 is released, user authorization (and access tokens) are required for all API 1.1 requests. In the weeks following release, some methods will require only application-based authentication for certain "userless" contexts.

Will an application have to request user authorization just to make public API calls?

When API v1.1 is released, user authorization (and access tokens) are required for all API 1.1 requests. In the weeks following release, some methods will require only application-based authentication for certain "userless" contexts.

Rules and Policies

Do the display requirements apply to mobile apps and Twitter clients also?

Yes. Our display requirements cover mobile. See Developer Display Requirements.

Does the 100,000 access token limit apply to all applications? Who does the 100,000 access token limit apply to?

The 100,000 token limit only applies to traditional Twitter client applications, which represent only a small share of the broader Twitter ecosystem. This token limit does not apply to any other applications.

How do I contest an application suspension?

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

How do I know how many access tokens my application has?

At this time you'll have to contact the platform team to learn how many access tokens your application definitively has. You are encouraged to track your access token count independently, acknowledging that you will not be aware of every access revocation.

How is the access token count calculated?

The access token count is calculated against the number of valid tokens that an application can use to make an API request. This is the total number of tokens your application has procured, minus those tokens that have either been revoked by the user, or our trust and safety team.

I'm not a developer, how do I render tweets according to display requirements?

You can review our Developer Display Requirements. Embedded Tweets and Embedded Timelines are easy ways to implement display requirements.

In API v1.1 will developers be allowed include additional actions on Tweets such as "Send to Instagram," "Send Email," "Tweet of the Day?"

No. Please leave the integrity of the Tweet intact. If you feel compelled to add additional content, please do so around or adjacent to the Tweet, but not within the actual Tweet itself. If you’re concerned about staying inline with our Developer Display Requirements, please see our Embedded Tweets and Embedded Timelines products.

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 have sufficiently diagnosed your network connectivity and believe your IP may have been blacklisted, please post to the discussion forums.. Provide as much detail as possible about which steps you've taken to diagnose.

Is there any token limit for non-client applications?

If you think you’re going to need more than 1 million tokens, please plan to come and talk with us as you approach that number.

Why are automated and bulk following/unfollowing services not allowed?

First, it’s worth clarifying that this policy change isn’t meant to prevent developers from building tools that surface potential accounts to follow or unfollow. However, the follow/unfollow action must happen one account at a time, not in bulk.

After hearing feedback from users who rely on third-party tools for follow management, we want to provide more context behind this policy change. Per the Twitter Rules, following or unfollowing large amounts of users in a short time period is considered to be a spam activity. Bulk and automated following behaviors are used by spammers to garner unsolicited attention and artificially inflate follower counts, frequently due to the perception that users should follow-back. In addition to spam, this behavior often leads to unusable timelines and direct messages inboxes. To discourage these activities, automated and bulk unfollowing is also disallowed.

We understand that there are people and businesses who have good intentions when they bulk follow/unfollow and who aren’t looking to engage in spam activities. However, to help us prevent spam and maintain a positive Twitter experience for users, we have disallowed all forms of this activity.