Twitter, Inc. - API Twitter

GET

/account/settings.json

Returns settings (including current trend, geo and sleep time information) for the authenticating user.

Request

Query

Name	Data Type	Description
`trend_location_woeid`	string	The Yahoo! Where On Earth ID to use as the user's default trend location. Global information is available by using 1 as the WOEID. The woeid must be one of the locations returned by GET trends/available. Example Values: 1
`sleep_time_enabled`	string	When set to true, t or 1, will enable sleep time for the user. Sleep time is the time when push or SMS notifications should not be sent to the user. Example Values: true
`start_sleep_time`	string	The hour that sleep time should begin if it is enabled. The value for this parameter should be provided in ISO8601 format (i.e. 00-23). The time is considered to be in the same timezone as the user's time_zone setting. Example Values: 13
`end_sleep_time`	string	The hour that sleep time should end if it is enabled. The value for this parameter should be provided in ISO8601 format (i.e. 00-23). The time is considered to be in the same timezone as the user's time_zone setting. Example Values: 13
`time_zone`	string	The timezone dates and times should be displayed in for the user. The timezone must be one of the Rails TimeZone names. Example Values: Europe/Copenhagen, Pacific/Tongatapu
`lang`	string	The language which Twitter should render in for this user. The language must be specified by the appropriate two letter ISO 639-1 representation. Currently supported languages are provided by GET help/languages. Example Values: it, en, es

Responses

200Successful Response

POST

/account/settings.json

Updates the authenticating user's settings.

Request

Query

Name	Data Type	Description
`trend_location_woeid`	string	The Yahoo! Where On Earth ID to use as the user's default trend location. Global information is available by using 1 as the WOEID. The woeid must be one of the locations returned by GET trends/available. Example Values: 1
`sleep_time_enabled`	string	When set to true, t or 1, will enable sleep time for the user. Sleep time is the time when push or SMS notifications should not be sent to the user. Example Values: true
`start_sleep_time`	string	The hour that sleep time should begin if it is enabled. The value for this parameter should be provided in ISO8601 format (i.e. 00-23). The time is considered to be in the same timezone as the user's time_zone setting. Example Values: 13
`end_sleep_time`	string	The hour that sleep time should end if it is enabled. The value for this parameter should be provided in ISO8601 format (i.e. 00-23). The time is considered to be in the same timezone as the user's time_zone setting. Example Values: 13
`time_zone`	string	The timezone dates and times should be displayed in for the user. The timezone must be one of the Rails TimeZone names. Example Values: Europe/Copenhagen, Pacific/Tongatapu
`lang`	string	The language which Twitter should render in for this user. The language must be specified by the appropriate two letter ISO 639-1 representation. Currently supported languages are provided by GET help/languages. Example Values: it, en, es

Responses

200Successful Response

POST

/account/update_delivery_device.json

Sets which device Twitter delivers updates to for the authenticating user. Sending none as the device parameter will disable SMS updates.

Request

Query

Name	Data Type	Description
`device`	string	Must be one of: sms, none. Example Values: sms
`include_entities`	string	When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more detail on entities. Example Values: true

Responses

200Successful Response

POST

/account/update_profile.json

Sets values that users are able to set under the Account tab of their settings page. Only the parameters specified will be updated.

Request

Query

Name	Data Type	Description
`name`	string	Full name associated with the profile. Maximum of 20 characters. Example Values: Marcel Molina
`url`	string	URL associated with the profile. Will be prepended with "http://" if not present. Maximum of 100 characters. Example Values: http://project.ioni.st
`location`	string	The city or country describing where the user of the account is located. The contents are not normalized or geocoded in any way. Maximum of 30 characters. Example Values: San Francisco, CA
`description`	string	A description of the user owning the account. Maximum of 160 characters. Example Values: Flipped my wig at age 22 and it never grew back. Also: I work at Twitter.
`include_entities`	string	The entities node will not be included when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

POST

/account/update_profile_background_image.json

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.

Request

Query

Name	Data Type	Description
`tile`	string	Whether or not to tile the background image. If set to true, t or 1 the background image will be displayed tiled. The image will not be tiled otherwise.
`use`	string	Determines whether to display the profile background image or not. When set to true, t or 1 the background image will be displayed if an image is being uploaded with the request, or has been uploaded previously. An error will be returned if you try to use a background image when one is not being uploaded or does not exist. If this parameter is defined but set to anything other than true, t or 1, the background image will stop being used.
`include_entities`	string	The entities node will not be included when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Header

Name	Data Type	Description
`Content-Type`	string Default value: `multipart/form-data`	Content type header

Responses

200Successful Response

POST

/account/update_profile_colors.json

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

Request

Query

Name	Data Type	Description
`profile_background_color`	string	Profile background color. Example Values: 3D3D3D
`profile_link_color`	string	Profile link color.Example Values: 0000FF
`profile_sidebar_border_color`	string	Profile sidebar's border color. Example Values: 0F0F0F
`profile_sidebar_fill_color`	string	Profile sidebar's background color. Example Values: 00FF00
`profile_text_color`	string	Profile text color. Example Values: 000000
`include_entities`	string	The entities node will not be included when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

POST

/account/update_profile_image.json

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 information, or, at least 5 seconds after uploading the image, ask for the updated URL using GET users/profile_image/:screen_name (https://dev.twitter.com/docs/api/1/get/users/profile_image/:screen_name).

Request

Query

Name	Data Type	Description
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Header

Name	Data Type	Description
`Content-Type`	string Default value: `multipart/form-data`	Content type header

Responses

200Successful Response

GET

/application/rate_limit_status.json

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

This method responds with a map of methods belonging to the families specified by the resources parameter, the current remaining uses for each of those resources within the current rate limiting window, and its expiration time in epoch time. It also includes a rate_limit_context field that indicates the current access token context.

You may also issue requests to this method without any parameters to receive a map of all rate limited GET methods. If your application only uses a few of methods, please explicitly provide a resources parameter with the specified resource families you work with.

Request

Query

Name	Data Type	Description
`resources`	string	A comma-separated list of resource families you want to know the current rate limit disposition for. For best performance, only specify the resource families pertinent to your application.Example Values: statuses,friends,trends,help

Responses

200Successful Response

POST

/blocks/create.json

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.

Request

Query

Name	Data Type	Description
`include_entities`	string	The entities node will not be included when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

POST

/blocks/destroy.json

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.

Request

Query

Name	Data Type	Description
`include_entities`	string	The entities node will not be included when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

GET

/blocks/ids.json

Returns an array of numeric user ids the authenticating user is blocking.

Request

Query

Name	Data Type	Description
`stringify_ids`	string	Many programming environments will not consume our ids due to their size. Provide this option to have ids returned as strings instead. Read more about Twitter IDs, JSON and Snowflake. Example Values: true
`cursor`	string	Causes the list of blocked users to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first "page." The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See Using cursors to navigate collections for more information. Example Values: 12893764510938

Responses

200Successful Response

GET

/blocks/list.json

Allows one to enable or disable retweets and device notifications from the specified user.

Request

Query

Name	Data Type	Description
`include_entities`	string	The entities node will not be included when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.
`cursor`	string	Causes the list of blocked users to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first "page." The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See Using cursors to navigate collections for more information. Example Values: 12893764510938

Responses

200Successful Response

GET

/direct_messages.json

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, write and direct message) permissions. Consult The Application Permission Model for more information.

Request

Query

Name	Data Type	Description
`count`	string	Specifies the number of direct messages to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of Tweets to return because suspended or deleted content is removed after the count has been applied. Example Values: 5
`since_id`	string	Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available. Example Values: 12345
`max_id`	string	Returns results with an ID less than (that is, older than) or equal to the specified ID. Example Values: 54321
`include_entities`	string	The entities node will not be included when set to false. Example Values: false
`page`	string	Specifies the page of results to retrieve. Example Values: 3
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

POST

/direct_messages/destroy.json

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 and direct message) permissions. Consult The Application Permission Model for more information.

Request

Query

Name	Data Type	Description
`id`	string	The ID of the direct message to delete. Example Values: 1270516771
`include_entities`	string	The entities node will not be included when set to false. Example Values: false

Responses

200Successful Response

POST

/direct_messages/new.json

Name	Data Type	Description
`text`	string	The text of your direct message. Be sure to URL encode as necessary, and keep the message under 140 characters. Example Values: Meet me behind the cafeteria after school

GET

/direct_messages/sent.json

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, write and direct message) permissions. Consult The Application Permission Model for more information.

Request

Query

Name	Data Type	Description
`count`	string	Specifies the number of direct messages to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of Tweets to return because suspended or deleted content is removed after the count has been applied. Example Values: 5
`since_id`	string	Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available. Example Values: 12345
`max_id`	string	Returns results with an ID less than (that is, older than) or equal to the specified ID. Example Values: 54321
`include_entities`	string	The entities node will not be included when set to false. Example Values: false
`page`	string	Specifies the page of results to retrieve. Example Values: 3

Responses

200Successful Response

GET

/direct_messages/show.json

Name	Data Type	Description
`id`	string	The ID of the direct message. Example Values: 587424932

POST

/favorites/create.json

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 method will indicate whether the intended action was successful or not.

Request

Query

Name	Data Type	Description
`id`	string	The numerical ID of the desired status. Example Values: 123
`include_entities`	string	The entities node will be omitted when set to false. Example Values: false

Responses

200Successful Response

POST

/favorites/destroy.json

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 tweet. A 200 OK response from this method will indicate whether the intended action was successful or not.

Request

Query

Name	Data Type	Description
`id`	string	The numerical ID of the desired status. Example Values: 123
`include_entities`	string	The entities node will be omitted when set to false. Example Values: false

Responses

200Successful Response

GET

/favorites/list.json

Returns the 20 most recent Tweets favorited by the authenticating or specified user.

Request

Query

Name	Data Type	Description
`count`	string	Specifies the number of records to retrieve. Must be less than or equal to 200. Defaults to 20. Example Values: 5
`since_id`	string	Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available. Example Values: 12345
`max_id`	string	Returns results with an ID less than (that is, older than) or equal to the specified ID. Example Values: 54321
`include_entities`	string	The entities node will be omitted when set to false. Example Values: false

Responses

200Successful Response

GET

/followers/ids.json

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 IDs and multiple "pages" of results can be navigated through using the next_cursor value in subsequent requests. See Using cursors to navigate collections for more information.

This method is especially powerful when used in conjunction with GET users/lookup, a method that allows you to convert user IDs into full user objects in bulk.

Request

Query

Name	Data Type	Description
`stringify_ids`	string	Many programming environments will not consume our Tweet ids due to their size. Provide this option to have ids returned as strings instead. Example Values: true
`cursor`	string	Causes the list of connections to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first "page." The response from the API will include a previous_cursor and next_cursor to allow paging back and forth.Example Values: 12893764510938

Responses

200Successful Response

GET

/friends/ids.json

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. Results are given in groups of 5,000 user IDs and multiple "pages" of results can be navigated through using the next_cursor value in subsequent requests. See Using cursors to navigate collections for more information.

This method is especially powerful when used in conjunction with GET users/lookup, a method that allows you to convert user IDs into full user objects in bulk.

Request

Query

Name	Data Type	Description
`stringify_ids`	string	Many programming environments will not consume our Tweet ids due to their size. Provide this option to have ids returned as strings instead. Example Values: true
`cursor`	string	Causes the list of connections to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first "page." The response from the API will include a previous_cursor and next_cursor to allow paging back and forth.Example Values: 12893764510938

Responses

200Successful Response

POST

/friendships/create.json

Name	Data Type	Description
`follow`	string	Enable notifications for the target user. Example Values: true

POST

/friendships/destroy.json

GET

/friendships/incoming.json

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.

Request

Query

Name	Data Type	Description
`stringify_ids`	string	Many programming environments will not consume our Tweet ids due to their size. Provide this option to have ids returned as strings instead. Example Values: true
`cursor`	string	Causes the list of connections to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first "page." The response from the API will include a previous_cursor and next_cursor to allow paging back and forth.Example Values: 12893764510938

Responses

200Successful Response

GET

/friendships/lookup.json

GET

/friendships/outgoing.json

Returns a collection of numeric IDs for every protected user for whom the authenticating user has a pending follow request.

Request

Query

Name	Data Type	Description
`stringify_ids`	string	Many programming environments will not consume our Tweet ids due to their size. Provide this option to have ids returned as strings instead. Example Values: true
`cursor`	string	Causes the list of connections to be broken into pages of no more than 5000 IDs at a time. The number of IDs returned is not guaranteed to be 5000 as suspended users are filtered out after connections are queried. If no cursor is provided, a value of -1 will be assumed, which is the first "page." The response from the API will include a previous_cursor and next_cursor to allow paging back and forth.Example Values: 12893764510938

Responses

200Successful Response

GET

/friendships/show.json

Returns detailed information about the relationship between two arbitrary users.

Request

Query

Name	Data Type	Description
`source_id`	string	The user_id of the subject user. Example Values: 3191321
`source_screen_name`	string	The screen_name of the subject user. Example Values: raffi
`target_id`	string	The user_id of the target user. Example Values: 20
`target_screen_name`	string	The screen_name of the target user. Example Values: noradio

Responses

200Successful Response

POST

/friendships/update.json

Allows one to enable or disable retweets and device notifications from the specified user.

Request

Query

Name	Data Type	Description
`device`	string	Enable/disable device notifications from the target user. Example Values: true, false
`retweets`	string	Enable/disable retweets from the target user. Example Values: true, false

Responses

200Successful Response

GET

/geo/id/{place_id}.json

Name	Data Type	Description
`place_id`	string	A place in the world. These IDs can be retrieved from geo/reverse_geocode. Example Values: df51dec6f4ee2b2c

POST

/geo/places.json

Creates a new place object at the given latitude and longitude.

Before creating a place you need to query GET geo/similar_places with the latitude, longitude and name of the place you wish to create. The query will return an array of places which are similar to the one you wish to create, and a token. If the place you wish to create isn't in the returned array you can use the token with this method to create a new one.

Request

Query

Name	Data Type	Description
`attribute:street_address`	string	This parameter searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted. Learn more about Place Attributes. Example Values: 795%20Folsom%20St
`callback`	string	If supplied, the response will use the JSONP format with a callback of the given name.

Responses

200Successful Response

GET

/geo/reverse_geocode.json

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

Request

Query

Name	Data Type	Description
`lat`	string	The latitude to search around. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding long parameter. Example Values: 37.7821120598956
`long`	string	The longitude to search around. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding lat parameter. Example Values: -122.400612831116
`accuracy`	string	A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If this is not passed in, then it is assumed to be 0m. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.). Example Values: 5ft
`granularity`	string	This is the minimal granularity of place types to return and must be one of: poi, neighborhood, city, admin or country. If no granularity is provided for the request neighborhood is assumed. Setting this to city, for example, will find places which have a type of city, admin or country. Example Values: city
`max_results`	string	A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here. Example Values: 3
`callback`	string	If supplied, the response will use the JSONP format with a callback of the given name.

Responses

200Successful Response

GET

/geo/search.json

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, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location with a call to POST statuses/update.

This is the recommended method to use find places that can be attached to statuses/update. Unlike GET geo/reverse_geocode which provides raw data access, this endpoint can potentially re-order places with regards to the user who is authenticated. This approach is also preferred for interactive place matching with the user.

Request

Query

Name	Data Type	Description
`accuracy`	string	A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If this is not passed in, then it is assumed to be 0m. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.). Example Values: 5ft
`granularity`	string	This is the minimal granularity of place types to return and must be one of: poi, neighborhood, city, admin or country. If no granularity is provided for the request neighborhood is assumed. Setting this to city, for example, will find places which have a type of city, admin or country. Example Values: city
`contained_within`	string	This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found. Specify a place_id. For example, to scope all results to places within "San Francisco, CA USA", you would specify a place_id of "5a110d312052166f" Example Values: 247f43d441defc03
`attribute:street_address`	string	This parameter searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted. Learn more about Place Attributes. Example Values: 795%20Folsom%20St
`callback`	string	If supplied, the response will use the JSONP format with a callback of the given name.

Responses

200Successful Response

GET

/geo/similar_places.json

Locates places near the given coordinates which are similar in name.

Conceptually you would use this method to get a list of known places to choose from first. Then, if the desired place doesn't exist, make a request to POST geo/place to create a new one.

The token contained in the response is the token needed to be able to create a new place.

Request

Query

Name	Data Type	Description
`contained_within`	string	This is the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found. Specify a place_id. For example, to scope all results to places within "San Francisco, CA USA", you would specify a place_id of "5a110d312052166f" Example Values: 247f43d441defc03
`attribute:street_address`	string	This parameter searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted. Learn more about Place Attributes. Example Values: 795%20Folsom%20St
`callback`	string	If supplied, the response will use the JSONP format with a callback of the given name.

Responses

200Successful Response

GET

/help/configuration.json

GET

/help/languages.json

GET

/help/privacy.json

GET

/help/tos.json

POST

/lists/create.json

Creates a new list for the authenticated user. Note that you can't create more than 20 lists per account.

Request

Query

Name	Data Type	Description
`name`	string	The name for the list.A list's name must start with a letter and can consist only of 25 or fewer letters, numbers, "-", or "_" characters.
`mode`	string	Whether your list is public or private. Values can be public or private. If no mode is specified the list will be public.
`description`	string	The description to give the list.

Responses

200Successful Response

POST

/lists/destroy.json

Deletes the specified list. The authenticated user must own the list to be able to destroy it.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.

Responses

200Successful Response

GET

/lists/list.json

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 consistency with other call.

Request

Query

Name	Data Type	Description
`screen_name`	string	The screen name of the user for whom to return results for. Helpful for disambiguating when a valid screen name is also a user ID. Example Values: noradio
`user_id`	string	The ID of the user for whom to return results for. Helpful for disambiguating when a valid user ID is also a valid screen name. Example Values: 12345 Note:: Specifies the ID of the user to get lists from. Helpful for disambiguating when a valid user ID is also a valid screen name.

Responses

200Successful Response

GET

/lists/members.json

Returns the members of the specified list. Private list members will only be shown if the authenticated user owns the specified list.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`include_entities`	string	The entities node will be disincluded when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.
`cursor`	string	Causes the collection of list members to be broken into "pages" of somewhat consistent size. If no cursor is provided, a value of -1 will be assumed, which is the first "page." The response from the API will include a previous_cursor and next_cursor to allow paging back and forth. See Using cursors to navigate collections for more information. Example Values: 12893764510938

Responses

200Successful Response

POST

/lists/members/create.json

Add a member to a list. The authenticated user must own the list to be able to add members to it. Note that lists can't have more than 500 members.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.

Responses

200Successful Response

POST

/lists/members/create_all.json

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 500 members, and you are limited to adding up to 100 members to a list at a time with this method.

Please note that there can be issues with lists that rapidly remove and add memberships. Take care when using these methods such that you are not too rapidly switching between removals and adds on the same list.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`user_id`	string	A comma separated list of user IDs, up to 100 are allowed in a single request.
`screen_name`	string	A comma separated list of screen names, up to 100 are allowed in a single request.

Responses

200Successful Response

POST

/lists/members/destroy.json

Removes the specified member from the list. The authenticated user must be the list's owner to remove members from the list.

Request

Query

Name	Data Type	Description
`list_id`	string	The numerical id of the list.
`slug`	string	You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you'll also have to specify the list owner using the owner_id or owner_screen_name parameters.
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`user_id`	string	The ID of the user to remove from the list. Helpful for disambiguating when a valid user ID is also a valid screen name.
`screen_name`	string	The screen name of the user for whom to remove from the list. Helpful for disambiguating when a valid screen name is also a user ID.

Responses

200Successful Response

POST

/lists/members/destroy_all.json

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 time with this method.

Please note that there can be issues with lists that rapidly remove and add memberships. Take care when using these methods such that you are not too rapidly switching between removals and adds on the same list.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`screen_name`	string	A comma separated list of screen names, up to 100 are allowed in a single request.
`user_id`	string	A comma separated list of user IDs, up to 100 are allowed in a single request.

Responses

200Successful Response

GET

/lists/members/show.json

Check if the specified user is a member of the specified list.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`include_entities`	string	When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future.
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

GET

/lists/memberships.json

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.

Request

Query

Name	Data Type	Description
`user_id`	string	The ID of the user for whom to return results for. Helpful for disambiguating when a valid user ID is also a valid screen name.
`screen_name`	string	The screen name of the user for whom to return results for. Helpful for disambiguating when a valid screen name is also a user ID.
`cursor`	string	Breaks the results into pages. A single page contains 20 lists. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
`filter_to_owned_lists`	string	When set to true, t or 1, will return just lists the authenticating user owns, and the user represented by user_id or screen_name is a member of.

Responses

200Successful Response

GET

/lists/show.json

Returns the specified list. Private lists will only be shown if the authenticated user owns the specified list.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.

Responses

200Successful Response

GET

/lists/statuses.json

Returns tweet timeline for members of the specified list. Retweets are included by default. You can use the include_rts=false parameter to omit retweet objects.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`since_id`	string	Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
`max_id`	string	Returns results with an ID less than (that is, older than) or equal to the specified ID.
`count`	string	Specifies the number of results to retrieve per "page.
`include_entities`	string	Entities are ON by default in API 1.1, each tweet includes a node called "entities". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. You can omit entities from the result by using include_entities=false
`include_rts`	string	When set to either true, t or 1, the list timeline will contain native retweets (if they exist) in addition to the standard stream of tweets. The output format of retweeted tweets is identical to the representation you see in home_timeline.

Responses

200Successful Response

GET

/lists/subscribers.json

Returns the subscribers of the specified list. Private list subscribers will only be shown if the authenticated user owns the specified list.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`cursor`	string	Breaks the results into pages. A single page contains 20 lists. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
`include_entities`	string	When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more details.
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

POST

/lists/subscribers/create.json

Subscribes the authenticated user to the specified list.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.

Responses

200Successful Response

POST

/lists/subscribers/destroy.json

Unsubscribes the authenticated user from the specified list.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.

Responses

200Successful Response

GET

/lists/subscribers/show.json

Check if the specified user is a subscriber of the specified list. Returns the user if they are subscriber.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`include_entities`	string	When set to either true, t or 1, each tweet will include a node called "entities". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. While entities are opt-in on timelines at present, they will be made a default component of output in the future. See Tweet Entities for more details.
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

GET

/lists/subscriptions.json

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.

Request

Query

Name	Data Type	Description
`count`	string	The amount of results to return per page. Defaults to 20. Maximum of 1,000 when using cursors.
`cursor`	string	Breaks the results into pages. A single page contains 20 lists. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list. It is recommended to always use cursors when the method supports them.

Responses

200Successful Response

POST

/lists/update.json

Updates the specified list. The authenticated user must own the list to be able to update it.

Request

Query

Name	Data Type	Description
`owner_screen_name`	string	The screen name of the user who owns the list being requested by a slug.
`owner_id`	string	The user ID of the user who owns the list being requested by a slug.
`name`	string	The name for the list.
`mode`	string	Whether your list is public or private. Values can be public or private. If no mode is specified the list will be public.
`description`	string	The description to give the list.

Responses

200Successful Response

POST

/saved_searches/create.json

POST

/saved_searches/destroy/{id}.json

GET

/saved_searches/list.json

GET

/saved_searches/show/{id}.json

GET

/search/tweets.json

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 format of the Search API has been improved to return Tweet objects more similar to the objects you'll find across the REST API and platform. You may need to tolerate some inconsistencies and variance in perspectival values (fields that pertain to the perspective of the authenticating user) and embedded user objects.

Request

Query

Name	Data Type	Description
`q`	string	A UTF-8, URL-encoded search query of 1,000 characters maximum, including operators. Queries may additionally be limited by complexity.Example: @noradio.
`geocode`	string	Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by "latitude,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly. A maximum of 1,000 distinct "sub-regions" will be considered when using the radius modifier.
`lang`	string	Restricts tweets to the given language, given by an ISO 639-1 code. Language detection is best-effort.Example Values: eu
`locale`	string	Specify the language of the query you are sending (only ja is currently effective). This is intended for language-specific consumers and the default should work in the majority of cases.Example Values: ja
`result_type`	string	Optional. Specifies what type of search results you would prefer to receive. The current default is "mixed." Valid values include: mixed: Include both popular and real time results in the response. recent: return only the most recent results in the response popular: return only the most popular results in the response. Example Values: mixed, recent, popular
`count`	string	The number of tweets to return per page, up to a maximum of 100. Defaults to 15. This was formerly the "rpp" parameter in the old Search API. Example Values: 100
`until`	string	Returns tweets generated before the given date. Date should be formatted as YYYY-MM-DD. Keep in mind that the search index may not go back as far as the date you specify here. Example Values: 2012-09-01
`since_id`	string	Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available. Example Values: 12345
`max_id`	string	Returns results with an ID less than (that is, older than) or equal to the specified ID. Example Values: 12345
`include_entities`	string	The entities node will be disincluded when set to false. Example Values: false
`callback`	string	If supplied, the response will use the JSONP format with a callback of the given name. The usefulness of this parameter is somewhat diminished by the requirement of authentication for requests to this endpoint. Example Values: processTweets

Responses

200Successful Response

POST

/statuses/destroy/{id}.json

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.

Request

Path

Name	Data Type	Description
`id`	string	The numerical ID of the desired status.

Query

Name	Data Type	Description
`trim_user`	string	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.

Responses

200Successful Response

GET

/statuses/home_timeline.json

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 many users or follow users who tweet frequently.

Request

Query

Name	Data Type	Description
`count`	integer	Specifies the number of records to retrieve. Must be less than or equal to 200.
`max_id`	long	Returns results with an ID less than (that is, older than) or equal to the specified ID.
`since_id`	long	Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
`trim_user`	string	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
`exclude_replies`	string	This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets — this is because the count parameter retrieves that many tweets before filtering out retweets and replies.
`contributor_details`	string	This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.

Responses

200Successful Response

GET

/statuses/mentions_timeline.json

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 statuses.This method will include retweets in the JSON response regardless of whether the include_rts parameter is set.

Request

Query

Name	Data Type	Description
`count`	integer	Specifies the number of tweets to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. We include retweets in the count, even if include_rts is not supplied. It is recommended you always send include_rts=1 when using this API method.
`since_id`	long	Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
`max_id`	long	Returns results with an ID less than (that is, older than) or equal to the specified ID.
`trim_user`	string	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
`contributor_details`	string	This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.
`include_entities`	boolean	The entities node will be disincluded when set to false.

Responses

200Successful Response

GET

/statuses/oembed.json

Returns information allowing the creation of an embedded representation of a Tweet on third party sites. See the oEmbed specification (http://oembed.com) for information about the response format. Either the id or url parameters must be specified in a request, it is not necessary to include both. While this endpoint allows a bit of customization for the final appearance of the embedded Tweet, be aware that the appearance of the rendered Tweet may change over time to be consistent with Twitter's Display Guidelines (https://dev.twitter.com/terms/display-guidelines). Do not rely on any class or id parameters to stay constant in the returned markup.

Request

Query

Name	Data Type	Description
`maxwidth`	integer	The maximum width in pixels that the embed should be rendered at. This value is constrained to be between 250 and 550 pixels. Note that Twitter does not support the oEmbed maxheight parameter. Tweets are fundamentally text, and are therefore of unpredictable height that cannot be scaled like an image or video. Relatedly, the oEmbed response will not provide a value for height. Implementations that need consistent heights for Tweets should refer to the hide_thread and hide_media parameters below.
`hide_media`	string	Specifies whether the embedded Tweet should automatically expand images which were uploaded via POST statuses/update_with_media. When set to either true, t or 1 images will not be expanded. Defaults to false.
`hide_thread`	string	Specifies whether the embedded Tweet should automatically show the original message in the case that the embedded Tweet is a reply. When set to either true, t or 1 the original Tweet will not be shown. Defaults to false.
`omit_script`	string	Specifies whether the embedded Tweet HTML should include a 'script' element pointing to widgets.js. In cases where a page already includes widgets.js, setting this value to true will prevent a redundant script element from being included. When set to either true, t or 1 the 'script'element will not be included in the embed HTML, meaning that pages must include a reference to widgets.js manually. Defaults to false.
`align`	string Allowed values: - `left` - `right` - `center` - `none`	Specifies whether the embedded Tweet should be left aligned, right aligned, or centered in the page. Valid values are left, right, center, and none. Defaults to none, meaning no alignment styles are specified for the Tweet.
`related`	string	A value for the TWT related parameter, as described in Web Intents (https://dev.twitter.com/docs/intents). This value will be forwarded to all Web Intents calls. Example values: twitterapi, twittermedia, twitter.
`lang`	string	Language code for the rendered embed. This will affect the text and localization of the rendered HTML. Example value: fr

Responses

200Successful Response

POST

/statuses/retweet/{id}.json

Retweets a tweet. Returns the original tweet with retweet details embedded.

Request

Path

Name	Data Type	Description
`id`	string	The numerical ID of the desired status.

Query

Name	Data Type	Description
`trim_user`	string	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.

Responses

200Successful Response

GET

/statuses/retweets/{id}.json

Returns up to 100 of the first retweets of a given tweet.

Request

Path

Name	Data Type	Description
`id`	string	The numerical ID of the desired status.

Query

Name	Data Type	Description
`count`	string	Specifies the number of records to retrieve. Must be less than or equal to 100.
`trim_user`	string	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.

Responses

200Successful Response

GET

/statuses/show/{id}.json

Returns a single status, specified by the id parameter below. The status's author will be returned inline.

Request

Path

Name	Data Type	Description
`id`	string

Query

Name	Data Type	Description
`id`	string	The numerical ID of the desired status.
`trim_user`	string	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
`include_my_retweet`	string	When set to either true, t or 1, any Tweets returned that have been retweeted by the authenticating user will include an additional current_user_retweet node, containing the ID of the source status for the retweet.
`include_entities`	string	The entities node will be disincluded when set to false.

Responses

200Successful Response

POST

/statuses/update.json

Updates the authenticating user's status, also known as tweeting. To upload an image to accompany the tweet, use POST statuses/update_with_media (https://dev.twitter.com/docs/api/1/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 will be blocked, resulting in a 403 error. Therefore, a user cannot submit the same status twice in a row. While not rate limited by the API a user is limited in the number of tweets they can create at a time. If the number of updates posted by the user reaches the current allowed limit this method will return an HTTP 403 error.

Request

Query

Name	Data Type	Description
`status`	string Default value: `Posting from @apigee's API test console. It's like a command line for the Twitter API! #apitools`	The text of your status update, typically up to 140 characters. URL encode as necessary. t.co link short-url wrapping (https://dev.twitter.com/docs/tco-link-wrapper/faq) may effect character counts.
`in_reply_to_status_id`	string	The ID of an existing status that the update is in reply to. Note: This parameter will be ignored unless the author of the tweet this parameter references is mentioned within the status text. Therefore, you must include @username, where username is the author of the referenced tweet, within the update.
`lat`	string Default value: `37.426363`	The latitude of the location this tweet refers to. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding long parameter.
`long`	string Default value: `-122.141114`	The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding lat parameter.
`place_id`	string	A place in the world. These IDs can be retrieved from GET geo/reverse_geocode (https://dev.twitter.com/docs/api/1/get/geo/reverse_geocode).
`display_coordinates`	string Default value: `false` Allowed values: - `false` - `true` -	Whether or not to put a pin on the exact coordinates a tweet has been sent from.
`trim_user`	string	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.

Responses

200Successful Response

POST

/statuses/update_with_media.json

Updates the authenticating user's status and attaches media for upload. Unlike POST statuses/update (https://dev.twitter.com/docs/api/1.1/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[] parameter. The Tweet text will be rewritten to include the media URL(s), which will reduce the number of characters allowed in the Tweet text. If the URL(s) cannot be appended without text truncation, the tweet will be rejected and this method will return an HTTP 403 error. Important: Make sure that you're using upload.twitter.com as your host while posting statuses with media. It is strongly recommended to use SSL with this method.

Request

Query

Name	Data Type	Description
`status`	string	The text of your status update. URL encode as necessary. t.co link wrapping (https://dev.twitter.com/docs/tco-link-wrapper/faq) may affect character counts if the post contains URLs. You must additionally account for the characters_reserved_per_media per uploaded media, additionally accounting for space characters in between finalized URLs. Note: Request the GET help/configuration (https://dev.twitter.com/docs/api/1.1/get/help/configuration) endpoint to get the current characters_reserved_per_media and max_media_per_upload values.
`media`	string	Up to max_media_per_upload files may be specified in the request, each named media[]. Supported image formats are PNG, JPG and GIF. Animated GIFs are not supported. Note: Request the GET help/configuration (https://dev.twitter.com/docs/api/1.1/get/help/configuration) endpoint to get the current max_media_per_upload and photo_size_limit values.
`possibly_sensitive`	string	Set to true for content which may not be suitable for every audience.
`in_reply_to_status_id`	string	The ID of an existing status that the update is in reply to. Note: This parameter will be ignored unless the author of the tweet this parameter references is mentioned within the status text. Therefore, you must include @username, where username is the author of the referenced tweet, within the update.
`lat`	string	The latitude of the location this tweet refers to. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding long parameter. Example value: 37.7821120598956.
`long`	string	The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, not a number, geo_enabled is disabled, or if there not a corresponding lat parameter. Example value: -122.400612831116.
`place_id`	string	A place in the world identified by a Twitter place ID. Place IDs can be retrieved from geo/reverse_geocode.
`display_coordinates`	string	Whether or not to put a pin on the exact coordinates a tweet has been sent from.

Header

Name	Data Type	Description
`Content-Type`	string Default value: `multipart/form-data`	Content type.

Responses

200Successful Response

GET

/statuses/user_timeline.json

Returns the 20 most recent statuses posted by the authenticating user. It is also possible to request another user's timeline by using the screen_name or user_id parameter. The other users timeline will only be visible if they are not protected, or if the authenticating user's follow request was accepted by the protected user. The timeline returned is the equivalent of the one seen when you view a user's profile on twitter.com. This method can only return up to 3,200 of a user's most recent statuses. Native retweets of other statuses by the user is included in this total, regardless of whether include_rts is specified when requesting this resource. This method will not include retweets in the XML and JSON responses unless the include_rts parameter is set. The RSS and Atom responses will always include retweets as statuses prefixed with RT, regardless of provided parameters. Always specify either an user_id or screen_name when requesting a user timeline.

Request

Query

Name	Data Type	Description
`count`	integer	Specifies the number of tweets to try and retrieve, up to a maximum of 200. The value of count is best thought of as a limit to the number of tweets to return because suspended or deleted content is removed after the count has been applied. We include retweets in the count, even if include_rts is not supplied. It is recommended you always send include_rts=1 when using this API method.
`since_id`	long	Returns results with an ID greater than (that is, more recent than) the specified ID. There are limits to the number of Tweets which can be accessed through the API. If the limit of Tweets has occured since the since_id, the since_id will be forced to the oldest ID available.
`max_id`	long	Returns results with an ID less than (that is, older than) or equal to the specified ID.
`trim_user`	string	When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object.
`exclude_replies`	boolean	This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets — this is because the count parameter retrieves that many tweets before filtering out retweets and replies. This parameter is only supported for JSON and XML responses.
`contributor_details`	boolean	This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included.
`include_rts`	boolean	When set to false, the timeline will strip any native retweets (though they will still count toward both the maximal length of the timeline and the slice selected by the count parameter). Note: If you're using the trim_user parameter in conjunction with include_rts, the retweets will still contain a full user object.

Responses

200Successful Response

GET

/trends/available.json

GET

/trends/closest.json

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! Where On Earth ID.

Request

Query

Name	Data Type	Description
`lat`	string	If provided with a long parameter the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude is -180.0 to +180.0 (West is negative, East is positive) inclusive. Example Values: 37.781157
`long`	string	If provided with a lat parameter the available trend locations will be sorted by distance, nearest to furthest, to the co-ordinate pair. The valid ranges for longitude is -180.0 to +180.0 (West is negative, East is positive) inclusive. Example Values: -122.400612831116

Responses

200Successful Response

GET

/trends/place.json

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.

This information is cached for 5 minutes. Requesting more frequently than that will not return any more data, and will count against your rate limit usage.

Request

Query

Name	Data Type	Description
`id`	string	The Yahoo! Where On Earth ID of the location to return trending information for. Global information is available by using 1 as the WOEID.
`exclude`	string	Setting this equal to hashtags will remove all hashtags from the trends list.

Responses

200Successful Response

GET

/users/contributees.json

Returns a collection of users that the specified user can contribute to.

Request

Query

Name	Data Type	Description
`include_entities`	string	The entities node will be disincluded when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

GET

/users/contributors.json

Returns a collection of users who can contribute to the specified account.

Request

Query

Name	Data Type	Description
`include_entities`	string	The entities node will be disincluded when set to false. Example Values: false
`skip_status`	string	When set to either true, t or 1 statuses will not be included in the returned user objects.

Responses

200Successful Response

GET

/users/lookup.json

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

GET users/show is used to retrieve a single user object.

Request

Query

Name	Data Type	Description
`screen_name`	string	A comma separated list of screen names, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger (up to 100 screen names) requests. Example Values: twitterapi,twitter
`user_id`	string	A comma separated list of user IDs, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger requests. Example Values: 783214,6253282
`include_entities`	string	The entities node that may appear within embedded statuses will be disincluded when set to false. Example Values: false

Responses

200Successful Response

POST

/users/report_spam.json

GET

/users/search.json

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.

Request

Query

Name	Data Type	Description
`q`	string	The search query to run against people search. Example Values: Twitter%20API
`page`	string	Specifies the page of results to retrieve. Example Values: 3
`count`	string	The number of potential user results to retrieve per page. This value has a maximum of 20. Example Values: 5
`include_entities`	string	The entities node will be disincluded when set to false. Example Values: false

Responses

200Successful Response

GET

/users/show.json

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.

Request

Query

Name	Data Type	Description
`screen_name`	string	The screen name of the user for whom to return results for. Either a id or screen_name is required for this method. Example Values: noradio
`user_id`	string	The ID of the user for whom to return results for. Either an id or screen_name is required for this method. Example Values: 12345
`include_entities`	string	The entities node will be disincluded when set to false. Example Values: false

Responses

200Successful Response

GET

/users/suggestions.json

GET

/users/suggestions/{slug}.json

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.

Request

Path

Name	Data Type	Description
`slug`	string	The short name of list or a category Example Values: twitter

Query

Name	Data Type	Description
`lang`	string	Restricts the suggested categories to the requested language. The language must be specified by the appropriate two letter ISO 639-1 representation. Currently supported languages are provided by the GET help/languages API request. Unsupported language codes will receive English (en) results. If you use lang in this request, ensure you also include it when requesting the GET users/suggestions/:slug list.

Responses

200Successful Response

GET

/users/suggestions/{slug}/members.json

Twitter

Resources

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Header

Responses

Request

Query

Responses

Request

Query

Header

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Request

Query

Responses

Responses

Request

Query

Responses

Responses

Request

Query