Change

Twitter

Twitter: REST API v1.1 Resources

https://dev.twitter.com/docs/api/1.1

May 13, 2014

2.98% changed


Previous Version This Version

Timelines

Timelines are collections of Tweets, ordered with the most recent first.

Resource Description
GET statuses/mentions_timeline Returns the 20 most recent mentions (tweets containing a users's @screen_name) for the authenticating user. The timeline returned is the equivalent of the one seen when you view your mentions on twitter.com. This method can only return up to 800 tweets. See Working with Timelines for...
GET statuses/user_timeline Returns a collection of the most recent Tweets posted by the user indicated by the screen_name or user_id parameters. User timelines belonging to protected users may only be requested when the authenticated user either "owns" the timeline or is an approved follower of the owner. The timeline...
GET statuses/home_timeline Returns a collection of the most recent Tweets and retweets posted by the authenticating user and the users they follow. The home timeline is central to how most users interact with the Twitter service. Up to 800 Tweets are obtainable on the home timeline. It is more volatile for users that follow...
GET statuses/retweets_of_me Returns the most recent tweets authored by the authenticating user that have been retweeted by others. This timeline is a subset of the user's GET statuses/user_timeline. See Working with Timelines for instructions on traversing timelines.
Tweets

Tweets are the atomic building blocks of Twitter, 140-character status updates with additional associated metadata. People tweet for a variety of reasons about a multitude of topics.

Resource Description
GET statuses/retweets/:id Returns a collection of the 100 most recent retweets of the tweet specified by the id parameter.
GET statuses/show/:id Returns a single Tweet, specified by the id parameter. The Tweet's author will also be embedded within the tweet. See GET statuses/lookup for getting Tweets in bulk (up to 100 per call). See also Embeddable Timelines, Embeddable Tweets, and GET statuses/oembed for tools to render Tweets according...
POST statuses/destroy/:id Destroys the status specified by the required ID parameter. The authenticating user must be the author of the specified status. Returns the destroyed status if successful.
POST statuses/update Updates the authenticating user's current status, also known as tweeting. To upload an image to accompany the tweet, use POST statuses/update_with_media. For each update attempt, the update text is compared with the authenticating user's recent tweets. Any attempt that would result in duplication...
POST statuses/retweet/:id Retweets a tweet. Returns the original tweet with retweet details embedded.
POST statuses/update_with_media Updates the authenticating user's current status and attaches media for upload. In other words, it creates a Tweet with a picture attached. Unlike POST statuses/update, this method expects raw multipart data. Your POST request's Content-Type should be set to multipart/form-data with the media[]...
GET statuses/oembed Returns information allowing the creation of an embedded representation of a Tweet on third party sites. See the oEmbed specification for information about the response format. While this endpoint allows a bit of customization for the final appearance of the embedded Tweet, be aware that the...
GET statuses/retweeters/ids Returns a collection of up to 100 user IDs belonging to users who have retweeted the tweet specified by the id parameter. This method offers similar data to GET statuses/retweets/:id and replaces API v1's GET statuses/:id/retweeted_by/ids method.
Search

Find relevant Tweets based on queries performed by your users.

Resource Description
GET search/tweets Returns a collection of relevant Tweets matching a specified query. Please note that Twitter's search service and, by extension, the Search API is not meant to be an exhaustive source of Tweets. Not all Tweets will be indexed or made available via the search interface. In API v1.1, the response...
Streaming
Resource Description
POST statuses/filter Returns public statuses that match one or more filter predicates. Multiple parameters may be specified which allows most clients to use a single connection to the Streaming API. Both GET and POST requests are supported, but GET requests with too many parameters may cause the request to be...
GET statuses/sample Returns a small random sample of all public statuses. The Tweets returned by the default access level are the same, so if two different clients connect to this endpoint, they will see the same Tweets.
GET statuses/firehose This endpoint requires special permission to access. Returns all public statuses. Few applications require this level of access. Creative use of a combination of other resources and various access levels can satisfy nearly every application use case.
GET user Streams messages for a single user, as described in User streams.
GET site Streams messages for a set of users, as described in Site streams.
Direct Messages

Direct Messages are short, non-public messages sent between two users. Access to Direct Messages is governed by the The Application Permission Model.

Resource Description
GET direct_messages Returns the 20 most recent direct messages sent to the authenticating user. Includes detailed information about the sender and recipient user. You can request up to 200 direct messages per call, up to a maximum of 800 incoming DMs. Important: This method requires an access token with RWD (read,...
GET direct_messages/sent Returns the 20 most recent direct messages sent by the authenticating user. Includes detailed information about the sender and recipient user. You can request up to 200 direct messages per call, up to a maximum of 800 outgoing DMs. Important: This method requires an access token with RWD (read,...
GET direct_messages/show Returns a single direct message, specified by an id parameter. Like the /1.1/direct_messages.format request, this method will include the user objects of the sender and recipient. Important: This method requires an access token with RWD (read, write...
POST direct_messages/destroy Destroys the direct message specified in the required ID parameter. The authenticating user must be the recipient of the specified direct message. Important: This method requires an access token with RWD (read, write...
POST direct_messages/new Sends a new direct message to the specified user from the authenticating user. Requires both the user and text parameters and must be a POST. Returns the sent message in the requested format if successful.
Friends & Followers

Users follow their interests on Twitter through both one-way and mutual following relationships.

Resource Description
GET friendships/no_retweets/ids Returns a collection of user_ids that the currently authenticated user does not want to receive retweets from. Use POST friendships/update to set the "no retweets" status for a given user account on behalf of the current user.
GET friends/ids Returns a cursored collection of user IDs for every user the specified user is following (otherwise known as their "friends"). At this time, results are ordered with the most recent following first — however, this ordering is subject to unannounced change and eventual consistency issues....
GET followers/ids Returns a cursored collection of user IDs for every user following the specified user. At this time, results are ordered with the most recent following first — however, this ordering is subject to unannounced change and eventual consistency issues. Results are given in groups of 5,000 user...
GET friendships/incoming Returns a collection of numeric IDs for every user who has a pending request to follow the authenticating user.
GET friendships/outgoing Returns a collection of numeric IDs for every protected user for whom the authenticating user has a pending follow request.
POST friendships/create Allows the authenticating users to follow the user specified in the ID parameter. Returns the befriended user in the requested format when successful. Returns a string describing the failure condition when unsuccessful. If you are already friends with the user a HTTP 403 may be returned, though for...
POST friendships/destroy Allows the authenticating user to unfollow the user specified in the ID parameter. Returns the unfollowed user in the requested format when successful. Returns a string describing the failure condition when unsuccessful. Actions taken in this method are asynchronous and changes will be eventually...
POST friendships/update Allows one to enable or disable retweets and device notifications from the specified user.
GET friendships/show Returns detailed information about the relationship between two arbitrary users.
GET friends/list Returns a cursored collection of user objects for every user the specified user is following (otherwise known as their "friends"). At this time, results are ordered with the most recent following first — however, this ordering is subject to unannounced change and eventual consistency issues...
GET followers/list Returns a cursored collection of user objects for users following the specified user. At this time, results are ordered with the most recent following first — however, this ordering is subject to unannounced change and eventual consistency issues. Results are given in groups of 20 users and...
GET friendships/lookup Returns the relationships of the authenticating user to the comma-separated list of up to 100 screen_names or user_ids provided. Values for connections can be: following, following_requested, followed_by, none, blocking.
Users

Users are at the center of everything Twitter: they follow, they favorite, and tweet & retweet.

Resource Description
GET account/settings Returns settings (including current trend, geo and sleep time information) for the authenticating user.
GET account/verify_credentials Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; returns a 401 status code and an error message if not. Use this method to test if supplied user credentials are valid.
POST account/settings Updates the authenticating user's settings.
POST account/update_delivery_device Sets which device Twitter delivers updates to for the authenticating user. Sending none as the device parameter will disable SMS updates.
POST account/update_profile Sets values that users are able to set under the "Account" tab of their settings page. Only the parameters specified will be updated.
POST account/update_profile_background_image Updates the authenticating user's profile background image. This method can also be used to enable or disable the profile background image. Although each parameter is marked as optional, at least one of image, tile or use must be provided when making this request.
POST account/update_profile_colors Sets one or more hex values that control the color scheme of the authenticating user's profile page on twitter.com. Each parameter's value must be a valid hexidecimal value, and may be either three or six characters (ex: #fff or #ffffff).
POST account/update_profile_image Updates the authenticating user's profile image. Note that this method expects raw multipart data, not a URL to an image. This method asynchronously processes the uploaded file before updating the user's profile image URL. You can either update your local cache the next time you request the user's...
GET blocks/list Returns a collection of user objects that the authenticating user is blocking. Important On October 15, 2012 this method will become cursored by default, altering the default response format. See Using cursors to navigate collections for more details on how cursoring works.
GET blocks/ids Returns an array of numeric user ids the authenticating user is blocking. Important On October 15, 2012 this method will become cursored by default, altering the default response format. See Using cursors to navigate collections for more details on how cursoring works.
POST blocks/create Blocks the specified user from following the authenticating user. In addition the blocked user will not show in the authenticating users mentions or timeline (unless retweeted by another user). If a follow or friend relationship exists it is destroyed.
POST blocks/destroy Un-blocks the user specified in the ID parameter for the authenticating user. Returns the un-blocked user in the requested format when successful. If relationships existed before the block was instated, they will not be restored.
GET users/lookup Returns fully-hydrated user objects for up to 100 users per request, as specified by comma-separated values passed to the user_id and/or screen_name parameters. This method is especially useful when used in conjunction with collections of user IDs returned from GET friends/ids and GET followers/...
GET users/show Returns a variety of information about the user specified by the required user_id or screen_name parameter. The author's most recent Tweet will be returned inline when possible. GET users/lookup is used to retrieve a bulk collection of user objects.
GET users/search Provides a simple, relevance-based search interface to public user accounts on Twitter. Try querying by topical interest, full name, company name, location, or other criteria. Exact match searches are not supported. Only the first 1,000 matching results are available.
GET users/contributees Returns a collection of users that the specified user can "contribute" to.
GET users/contributors Returns a collection of users who can contribute to the specified account.
POST account/remove_profile_banner Removes the uploaded profile banner for the authenticating user. Returns HTTP 200 upon success.
POST account/update_profile_banner Uploads a profile banner on behalf of the authenticating user. For best results, upload an
GET users/profile_banner Returns a map of the available size variations of the specified user's profile banner. If the user has not uploaded a profile banner, a HTTP 404 will be served instead. This method can be used instead of string manipulation on the profile_banner_url returned in user objects as described in User...
POST mutes/users/create Link: /docs/api/1.1/post/mutes/users/create Mutes the user specified in the ID parameter for the authenticating user. Returns the muted user in the requested format when successful. Returns a string describing the failure condition when unsuccessful. Actions taken in this method are asynchronous and changes will be eventually consistent.
POST mutes/users/destroy Link: /docs/api/1.1/post/mutes/users/destroy Un-mutes the user specified in the ID parameter for the authenticating user. Returns the unmuted user in the requested format when successful. Returns a string describing the failure condition when unsuccessful. Actions taken in this method are asynchronous and changes will be eventually...
GET mutes/users/ids Link: /docs/api/1.1/get/mutes/users/ids Returns an array of numeric user ids the authenticating user has muted.
GET mutes/users/list Link: /docs/api/1.1/get/mutes/users/list Returns an array of user objects the authenticating user has muted.
Suggested Users

Categorical organization of users that others may be interested to follow.

Resource Description
GET users/suggestions/:slug Access the users in a given category of the Twitter suggested user list. It is recommended that applications cache this data for no more than one hour.
GET users/suggestions Access to Twitter's suggested user list. This returns the list of suggested user categories. The category can be used in GET users/suggestions/:slug to get the users in that category.
GET users/suggestions/:slug/members Access the users in a given category of the Twitter suggested user list and return their most recent status if they are not a protected user.
Favorites

Users favorite tweets to give recognition to awesome tweets, to curate the best of Twitter, to save for reading later, and a variety of other reasons. Likewise, developers make use of "favs" in many different ways.

Resource Description
GET favorites/list Returns the 20 most recent Tweets favorited by the authenticating or specified user.
POST favorites/destroy Un-favorites the status specified in the ID parameter as the authenticating user. Returns the un-favorited status in the requested format when successful. This process invoked by this method is asynchronous. The immediately returned status may not indicate the resultant favorited status of the...
POST favorites/create Favorites the status specified in the ID parameter as the authenticating user. Returns the favorite status when successful. This process invoked by this method is asynchronous. The immediately returned status may not indicate the resultant favorited status of the tweet. A 200 OK response from this...
Lists

Lists are collections of tweets, culled from a curated list of Twitter users. List timeline methods include tweets by all members of a list.

Resource Description
GET lists/list Returns all lists the authenticating or specified user subscribes to, including their own. The user is specified using the user_id or screen_name parameters. If no user is given, the authenticating user is used. This method used to be GET lists in version 1.0 of the API and has been renamed for...
GET lists/statuses Returns a timeline of tweets authored by members of the specified list. Retweets are included by default. Use the include_rts=false parameter to omit retweets. Embedded Timelines is a great way to embed list timelines on your website.
POST lists/members/destroy Removes the specified member from the list. The authenticated user must be the list's owner to remove members from the list.
GET lists/memberships Returns the lists the specified user has been added to. If user_id or screen_name are not provided the memberships for the authenticating user are returned.
GET lists/subscribers Returns the subscribers of the specified list. Private list subscribers will only be shown if the authenticated user owns the specified list.
POST lists/subscribers/create Subscribes the authenticated user to the specified list.
GET lists/subscribers/show Check if the specified user is a subscriber of the specified list. Returns the user if they are subscriber.
POST lists/subscribers/destroy Unsubscribes the authenticated user from the specified list.
POST lists/members/create_all Adds multiple members to a list, by specifying a comma-separated list of member ids or screen names. The authenticated user must own the list to be able to add members to it. Note that lists can't have more than 5,000 members, and you are limited to adding up to 100 members to a list at a time with...
GET lists/members/show Check if the specified user is a member of the specified list.
GET lists/members Returns the members of the specified list. Private list members will only be shown if the authenticated user owns the specified list.
POST lists/members/create Add a member to a list. The authenticated user must own the list to be able to add members to it. Note that lists cannot have more than 5,000 members.
POST lists/destroy Deletes the specified list. The authenticated user must own the list to be able to destroy it.
POST lists/update Updates the specified list. The authenticated user must own the list to be able to update it.
POST lists/create Creates a new list for the authenticated user. Note that you can't create more than 20 lists per account.
GET lists/show Returns the specified list. Private lists will only be shown if the authenticated user owns the specified list.
GET lists/subscriptions Obtain a collection of the lists the specified user is subscribed to, 20 lists per page by default. Does not include the user's own lists.
POST lists/members/destroy_all Removes multiple members from a list, by specifying a comma-separated list of member ids or screen names. The authenticated user must own the list to be able to remove members from it. Note that lists can't have more than 500 members, and you are limited to removing up to 100 members to a list at a...
GET lists/ownerships Returns the lists owned by the specified Twitter user. Private lists will only be shown if the authenticated user is also the owner of the lists.
Saved Searches

Allows users to save references to search criteria for reuse later.

Resource Description
GET saved_searches/list Returns the authenticated user's saved search queries.
GET saved_searches/show/:id Retrieve the information for the saved search represented by the given id. The authenticating user must be the owner of saved search ID being requested.
POST saved_searches/create Create a new saved search for the authenticated user. A user may only have 25 saved searches.
POST saved_searches/destroy/:id Destroys a saved search for the authenticating user. The authenticating user must be the owner of saved search id being destroyed.
Places & Geo

Users tweet from all over the world. These methods allow you to attach location data to tweets and discover tweets & locations.

Resource Description
GET geo/id/:place_id Returns all the information about a known place.
GET geo/reverse_geocode Given a latitude and a longitude, searches for up to 20 places that can be used as a place_id when updating a status. This request is an informative call and will deliver generalized results about geography.
GET geo/search Search for places that can be attached to a statuses/update. Given a latitude and a longitude pair, an IP address, or a name, this request will return a list of all the valid places that can be used as the place_id when updating a status. Conceptually, a query can be made from the user's location...
GET geo/similar_places Locates places near the given coordinates which are similar in name.
POST geo/place As of December 2nd, 2013, this endpoint is deprecated and retired and no longer functions. Place creation was used infrequently by third party applications and is generally no longer supported on Twitter. Requests will return with status 410 (Gone) with error code 251. Follow the discussion about...
Trends

With so many tweets from so many users, themes are bound to arise from the zeitgeist. The Trends methods allow you to explore what's trending on Twitter.

Resource Description
GET trends/place Returns the top 10 trending topics for a specific WOEID, if trending information is available for it. The response is an array of "trend" objects that encode the name of the trending topic, the query parameter that can be used to search for the topic on Twitter Search, and the Twitter Search URL....
GET trends/available Returns the locations that Twitter has trending topic information for. The response is an array of "locations" that encode the location's WOEID and some other human-readable information such as a canonical name and country the location belongs in. A WOEID is a Yahoo! Where On Earth ID.
GET trends/closest Returns the locations that Twitter has trending topic information for, closest to a specified location. The response is an array of "locations" that encode the location's WOEID and some other human-readable information such as a canonical name and country the location belongs in. A WOEID is a Yahoo...
Spam Reporting

These methods are used to report user accounts as spam accounts.

Resource Description
POST users/report_spam Report the specified user as a spam account to Twitter. Additionally performs the equivalent of POST blocks/create on behalf of the authenticated user.
OAuth

Twitter uses OAuth for authentication. Be sure and read about Authentication & Authorization.

Resource Description
GET oauth/authenticate Allows a Consumer application to use an OAuth request_token to request user authorization. This method is a replacement of Section 6.2 of the OAuth 1.0 authentication flow for applications using the callback authentication flow. The method will use the currently logged in user as the account for...
GET oauth/authorize Allows a Consumer application to use an OAuth Request Token to request user authorization. This method fulfills Section 6.2 of the OAuth 1.0 authentication flow. Desktop applications must use this method (and cannot use GET oauth/authenticate). Please use HTTPS for this method, and all other OAuth...
POST oauth/access_token Allows a Consumer application to exchange the OAuth Request Token for an OAuth Access Token. This method fulfills Section 6.3 of the OAuth 1.0 authentication flow. The OAuth access token may also be used for xAuth operations. Please use HTTPS for this method, and all other OAuth token negotiation...
POST oauth/request_token Allows a Consumer application to obtain an OAuth Request Token to request user authorization. This method fulfills Section 6.1 of the OAuth 1.0 authentication flow. It is strongly recommended you use HTTPS for all OAuth authorization steps. Usage Note: Only ASCII values are accepted for the...
POST oauth2/token Allows a registered application to obtain an OAuth 2 Bearer Token, which can be used to make API requests on an application's own behalf, without a user context. This is called Application-only authentication. A Bearer Token may be invalidated using oauth2/invalidate_token. Once a Bearer Token has...
POST oauth2/invalidate_token Allows a registered application to revoke an issued OAuth 2 Bearer Token by presenting its client credentials. Once a Bearer Token has been invalidated, new creation attempts will yield a different Bearer Token and usage of the invalidated token will no longer be allowed. As with all API v1.1...
Help

These methods assist you in working & debugging with the Twitter API.

Resource Description
GET help/configuration Returns the current configuration used by Twitter including twitter.com slugs which are not usernames, maximum photo resolutions, and t.co URL lengths. It is recommended applications request this endpoint when they are loaded, but no more than once a day.
GET help/languages Returns the list of languages supported by Twitter along with their ISO 639-1 code. The ISO 639-1 code is the two letter value to use if you include lang with any of your requests.
GET help/privacy Returns Twitter's Privacy Policy.
GET help/tos Returns the Twitter Terms of Service in the requested format. These are not the same as the Developer Rules of the Road.
GET application/rate_limit_status Returns the current rate limits for methods belonging to the specified resource families. Each 1.1 API resource belongs to a "resource family" which is indicated in its method documentation. You can typically determine a method's resource family from the first component of the path after the...
Tweets
Resource Description
GET statuses/lookup Returns fully-hydrated tweet objects for up to 100 tweets per request, as specified by comma-separated values passed to the id parameter. This method is especially useful to get the details (hydrate) a collection of Tweet IDs. GET statuses/show/:id is used to retrieve a single tweet object.
.