Twitter offers applications the ability to issue authenticated requests on
behalf of the application itself (as opposed to on behalf of a specific user).
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
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.
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 (integer
) 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 (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 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 Tweets. Native
retweets of other statuses by the user is included in this total, regardless
of whether include_rts is set to false when requesting this resource.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
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.
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
since_id (integer
) 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.
count (integer
) Specifies the number of tweets to try and retrieve, up to a maximum of
200 per distinct request. 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.
max_id (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
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.
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. This parameter is
only supported for JSON and XML responses.
include_rts (string
) 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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
See Working with Timelines for instructions on traversing timelines efficiently.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
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.
count (integer
) Specifies the number of records to retrieve. Must be less than or equal
to 200.
since_id (integer
) 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 (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
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. This parameter is
only supported for JSON and XML responses.
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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
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.
count (integer
) Specifies the number of records to retrieve. Must be less than or equal
to 100. If omitted, 20 will be assumed.
since_id (integer
) 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 (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
include_user_entities (string
) The user entities node will be disincluded when set to false.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns a collection of the 100 most recent retweets of the tweet specified
by the id parameter.
Request
Uri Parameters
id (integer
) The numerical ID of the desired status.
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
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.
count (integer
) Specifies the number of records to retrieve. Must be less than or equal
to 100.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns a single Tweet, specified by the id parameter. The Tweet's author
will also be embedded within the tweet.
Extended description
About Geo
If there is no geotag for a status, then there will be an empty <geo/> or
"geo" : {}. This can only be populated if the user has used the Geotagging
API to send a statuses/update.
The JSON response mostly uses conventions laid out in GeoJSON. Unfortunately,
the coordinates that Twitter renders are reversed from the GeoJSON specification
(GeoJSON specifies a longitude then a latitude, whereas we are currently
representing it as a latitude then a longitude). Our JSON renders as:
-------------
"geo": { "type":"Point", "coordinates":[37.78029, -122.39697] }
Contributors
If there are no contributors for a Tweet, then there will be an empty or
"contributors" : {}. This field will only be populated if the user has
contributors enabled on his or her account -- this is a beta feature that
is not yet generally available to all.
This object contains an array of user IDs for users who have contributed
to this status (an example of a status that has been contributed to is this
one). In practice, there is usually only one ID in this array. The JSON
renders as such
-------------
"contributors":[8285392].
Request
Uri Parameters
id (integer
) The numerical ID of the desired Tweet.
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
id (integer
) The numerical ID of the desired status.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
User is duplicating status or rate limit is exceeded.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Retweets a tweet. Returns the original tweet with retweet details embedded.
Request
Uri Parameters
id (integer
) The numerical ID of the desired status.
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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[] 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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The URL(s) cannot be appended without text truncation.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 appearance of the rendered Tweet may
change over time to be consistent with Twitter's Display Requirements. Do not
rely on any class or id parameters to stay constant in the returned markup.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
id (integer
) The Tweet/status ID to return embed code for.
url (string
) The URL of the Tweet/status to be embedded.
maxwidth (integer
) The maximum width in pixels that the embed should be rendered at.
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.
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.
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.
align (string
) 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. This
value will be forwarded to all Web Intents calls.
lang (string
) Language code for the rendered embed. This will affect the text and
localization of the rendered HTML.
Response
Http Status code
200
Example is not provided by twitter docs.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns a collection of up to 100 user IDs belonging to users who have
retweeted the tweet specified by the id parameter.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
id (integer
) The numerical ID of the desired status.
cursor (integer
) Causes the list of IDs to be broken into pages of no more than 100 IDs
at a time. The number of IDs returned is not guaranteed to be 100 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.
While this method supports the cursor parameter, the entire result set can
be returned in a single cursored collection. Using the count parameter with
this method will not provide segmented cursors for use with this parameter.
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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 rejected for excessive URL
length. Use a POST request to avoid long URLs.
The track, follow, and locations fields should be considered to be combined
with an OR operator. track=foo&follow=1234 returns Tweets matching "foo" OR
created by user 1234.
The default access level allows up to 400 track keywords, 5,000 follow userids
and 25 0.1-360 degree location boxes. If you need elevated access to the Streaming
API, you should explore our partner providers of Twitter data here.
Note: At least one predicate parameter (follow, locations, or track) must be specified.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Example is not provided by twitter docs.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
delimited (string
) Specifies whether messages should be length-delimited. See the delimited
parameter documentation for more information.
stall_warnings (string
) Specifies whether stall warnings should be delivered. See the stall_warnings
parameter documentation for more information.
Response
Http Status code
200
Example is not provided by twitter docs.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
count (integer
) The number of messages to backfill. See the count parameter documentation
for more information.
delimited (string
) Specifies whether messages should be length-delimited. See the delimited
parameter documentation for more information.
stall_warnings (string
) Specifies whether stall warnings should be delivered. See the stall_warnings
parameter documentation for more information.
Response
Http Status code
200
Example is not provided by twitter docs.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns a collection of relevant Tweets matching a specified query.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
q (string
) A UTF-8, URL-encoded search query of 1,000 characters maximum,
including operators. Queries may additionally be limited by complexity.
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.
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
ja
result_type (string
) 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.
count (integer
) The number of tweets to return per page, up to a maximum of 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.
since_id (integer
) 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 (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 & direct
message) permissions. Consult The Application Permission Model for more
information. (https://dev.twitter.com/docs/application-permission-model)
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
since_id (integer
) 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 (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
count (integer
) 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.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 &
direct message) permissions. Consult The Application Permission Model for
more information.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
since_id (integer
) 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 (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
count (integer
) 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.
page (integer
) Specifies the page of results to retrieve.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 &
direct message) permissions. Consult The Application Permission Model for
more information.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
id (integer
) The ID of the direct message.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 &
direct message) permissions. Consult The Application Permission Model for
more information.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
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. This parameter is especially
important to use in Javascript environments.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
screen_name (string
) A comma separated list of screen names, up to 100 are allowed in a single
request.
Example
twitterapi,twitter
user_id (string
) A comma separated list of user IDs, up to 100 are allowed in a single
request.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns a collection of numeric IDs for every user who has a pending request
to follow the authenticating user.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
cursor (integer
) 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. See Using cursors to navigate collections
for more information.
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. More
about Twitter IDs, JSON and Snowflake.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns a collection of numeric IDs for every protected user for whom the
authenticating user has a pending follow request.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
cursor (integer
) 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. See Using cursors to navigate collections
for more information.
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. More
about Twitter IDs, JSON and Snowflake.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 performance
reasons you may get a 200 OK message even if the friendship already exists.
Actions taken in this method are asynchronous and changes will be eventually
consistent.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
If you are already friends with the user.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
consistent.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Allows one to enable or disable retweets and device notifications from the
specified user.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns detailed information about the relationship between two arbitrary
users.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
source_id (integer
) The user_id of the subject user.
source_screen_name (string
) The screen_name of the subject user.
target_id (integer
) The user_id of the target user.
target_screen_name (string
) The screen_name of the target user.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
cursor (integer
) 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. See Using cursors to navigate collections
for more information.
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. More
about Twitter IDs, JSON and Snowflake.
count (integer
) Specifies the number of IDs attempt retrieval of, up to a maximum of 5,000
per distinct request. The value of count is best thought of as a limit to
the number of results to return. When using the count parameter with this
method, it is wise to use a consistent count value across all requests to
the same user's collection. Usage of this parameter is encouraged in
environments where all 5,000 IDs constitutes too large of a response.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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. Results are given in groups of 20 users 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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
cursor (integer
) 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. See Using cursors to navigate collections
for more information.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
include_user_entities (string
) The user object entities node will be disincluded when set to false.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
cursor (integer
) 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. See Using cursors to navigate collections
for more information.
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. More
about Twitter IDs, JSON and Snowflake.
count (integer
) Specifies the number of IDs attempt retrieval of, up to a maximum of 5,000
per distinct request. The value of count is best thought of as a limit to
the number of results to return. When using the count parameter with this
method, it is wise to use a consistent count value across all requests to
the same user's collection. Usage of this parameter is encouraged in
environments where all 5,000 IDs constitutes too large of a response.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
cursor (integer
) 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. See Using cursors to navigate collections
for more information.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
include_user_entities (string
) The user object entities node will be disincluded when set to false.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns settings (including current trend, geo and sleep time information)
for the authenticating user.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
POST
/account/settings{mediaTypeExtension}
Description
Updates the authenticating user's settings.
While all parameters for this method are optional, at least one or more
should be provided when executing this request.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Sets which device Twitter delivers updates to for the authenticating user.
Sending none as the device parameter will disable SMS updates.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Examples are not provided by twitter docs.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Sets values that users are able to set under the "Account" tab of their
settings page. Only the parameters specified will be updated.
While no specific parameter is required, at least one of these parameters
should be provided when executing this method.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Profile updated.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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/show.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Uploads a profile banner on behalf of the authenticating user. For best
results, upload an <5MB image that is exactly 1252px by 626px. Images will
be resized for a number of display options. Users with an uploaded profile
banner will have a profile_banner_url node in their Users objects. More
information about sizing variations can be found in User Profile Images
and Banners and GET users/profile_banner.
Profile banner images are processed asynchronously. The profile_banner_url
and its variant sizes will not necessary be available directly after upload.
Note: If providing any one of the height, width, offset_left, or offset_top
parameters, you must provide all of the sizing parameters.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Profile banner image succesfully uploaded.
Http Status code
304
There was no new data to return.
Http Status code
400
Either an image was not provided or the image data could not be processed.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
The image could not be resized or is too large.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Removes the uploaded profile banner for the authenticating user. Returns
HTTP 200 upon success.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Response
Http Status code
200
Profile banner deleted.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
cursor (integer
) 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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns an array of numeric user ids the authenticating user is blocking.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
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.
cursor (integer
) Causes the list of IDs 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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Either screen_name or user_id must be provided.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
One of screen_name or id must be provided.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
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
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
7832146253282
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
You must be following a protected user to be able to see their most recent
Tweet. If you don't follow a protected user, the users Tweet will be removed.
A Tweet will not always be returned in the current_status field.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
user_id (integer
) The ID of the user for whom to return results for. Either an id or
screen_name is required for this method.
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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
q (string
) The search query to run against people search.
page (string
) Specifies the page of results to retrieve.
count (integer
) The number of potential user results to retrieve per page. This value
has a maximum of 20.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns a collection of users that the specified user can "contribute" to.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
user_id (integer
) 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.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns a collection of users who can contribute to the specified account.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 Profile Images
and Banners.
The profile banner data available at each size variant's URL is in PNG format.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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}.json
to get the users in that category.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
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}.json list.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
slug (string
) The short name of list or a category
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
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.
Report the specified user as a spam account to Twitter. Additionally performs
the equivalent of POST blocks/create on behalf of the authenticated user.
One of parameters must be provided.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns the 20 most recent Tweets favorited by the authenticating or specified
user.
If you do not provide either a user_id or screen_name to this method, it
will assume you are requesting on behalf of the authenticating user. Specify
one or the other for best results.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
count (integer
) Specifies the number of records to retrieve. Must be less than or equal
to 200. Defaults to 20.
since_id (integer
) 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 (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
include_entities (string
) The entities node will be omitted when set to false.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
A maximum of 100 results will be returned by this call. Subscribed lists are
returned first, followed by owned lists. This means that if a user subscribes
to 90 lists and owns 20 lists, this method returns 90 subscriptions and 10 owned
lists. The reverse method returns owned lists first, so with reverse=true, 20
owned lists and 80 subscriptions would be returned. If your goal is to obtain
every list a user owns or subscribes to, use GET lists/ownerships and/or
GET lists/subscriptions instead.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) 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.
reverse (string
) Set this to true if you would like owned lists to be returned first. See
description above for information on how this parameter works.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
list_id (integer
) 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 (integer
) The user ID of the user who owns the list being requested by a slug.
since_id (integer
) 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 (integer
) Returns results with an ID less than (that is, older than) or equal to
the specified ID.
count (integer
) Specifies the number of results to retrieve per "page."
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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) 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 (integer
) Breaks the results into pages. 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. See
Using cursors to navigate collections for more information.
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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns the subscribers of the specified list. Private list subscribers will
only be shown if the authenticated user owns the specified list.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
list_id (integer
) 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 (integer
) The user ID of the user who owns the list being requested by a slug.
cursor (integer
) 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.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Subscribes the authenticated user to the specified list.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Check if the specified user is a subscriber of the specified list. Returns
the user if they are subscriber.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
owner_screen_name (string
) The screen name of the user who owns the list being requested by a slug.
owner_id (integer
) The user ID of the user who owns the list being requested by a slug.
list_id (integer
) 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.
user_id (integer
) 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.
Unsubscribes the authenticated user from the specified list.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Returns the members of the specified list. Private list members will only be
shown if the authenticated user owns the specified list.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
list_id (integer
) 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 (integer
) The user ID of the user who owns the list being requested by a slug.
cursor (integer
) 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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Removes the specified member from the list. The authenticated user must be
the list's owner to remove members from the list.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Member removed from list.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 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.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Members added.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Check if the specified user is a member of the specified list.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
include_entities (string
) The entities node will not be included when set to false.
list_id (integer
) 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.
user_id (integer
) 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.
owner_screen_name (string
) The screen name of the user who owns the list being requested by a slug.
owner_id (integer
) The user ID of the user who owns the list being requested by a slug.
skip_status (string
) When set to either true, t or 1 statuses will not be included in the
returned user objects.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Member added.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Deletes the specified list. The authenticated user must own the list to be
able to destroy it.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Updates the specified list. The authenticated user must own the list to be
able to update it.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
List updated.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Creates a new list for the authenticated user. Note that you can't create
more than 20 lists per account.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns the specified list. Private lists will only be shown if the
authenticated user owns the specified list.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
list_id (integer
) 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 (integer
) The user ID of the user who owns the list being requested by a slug.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
A user_id or screen_name must be provided.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) 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.
count (integer
) The amount of results to return per page. Defaults to 20. No more than
1000 results will ever be returned in a single page.
cursor (integer
) Breaks the results into pages. 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. See
Using cursors to navigate collections for more information.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Either a list_id or a slug is required. If providing a list_slug, an
owner_screen_name or owner_id is also required.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Members was removed from the list.
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
A user_id or screen_name must be provided.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
user_id (integer
) The ID of the user for whom to return results for.
screen_name (string
) The screen name of the user for whom to return results for.
count (integer
) The amount of results to return per page. Defaults to 20. No more than
1000 results will ever be returned in a single page.
cursor (string
) Breaks the results into pages. 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. See
Using cursors to navigate collections for more information.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns the authenticated user's saved search queries.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
id (integer
) The ID of the saved search.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Create a new saved search for the authenticated user. A user may only have
25 saved searches.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Destroys a saved search for the authenticating user. The authenticating
user must be the owner of saved search id being destroyed.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
id (integer
) The ID of the saved search.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
mediaTypeExtension (string
) Use .json to specify application/json media type.
place_id (string
) A place in the world. These IDs can be retrieved from geo/reverse_geocode.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
lat (number
) 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.
long (number
) 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.
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.).
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.
max_results (integer
) 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.
callback (string
) If supplied, the response will use the JSONP format with a callback of
the given name.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
lat (number
) 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.
long (number
) 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.
query (string
) Free-form text to match against while executing a geo-based query, best
suited for finding nearby locations by name. Remember to URL encode the query.
ip (string
) An IP address. Used when attempting to fix geolocation based off of the
user's IP address.
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.
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.).
max_results (integer
) 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.
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"
? "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.
callback (string
) If supplied, the response will use the JSONP format with a callback of
the given name.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
lat (number
) 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.
long (number
) 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.
name (string
) The name a place is known as.
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"
? "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.
callback (string
) If supplied, the response will use the JSONP format with a callback of
the given name.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Content-Type: application/x-www-form-urlencoded
Body
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
id (integer
) 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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
lat (number
) 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.
long (number
) 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.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
mediaTypeExtension (string
) Use .json to specify application/json media type.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
Returns the Twitter Terms of Service in the requested format. These are not
the same as the Developer Rules of the Road.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.
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 or application-only authentication 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.
When using app-only auth, this method's response indicates the app-only auth
rate limiting context.
Read more about REST API Rate Limiting in v1.1 and review the limits.
Request
Uri Parameters
mediaTypeExtension (string
) Use .json to specify application/json media type.
Query parameters
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.
See Rate Limiting in API v1.1 for more information.
Example
statuses,friends,trends,help
Response
Http Status code
200
Success!
Content-Type: application/json
Example
Schema
Http Status code
304
There was no new data to return.
Http Status code
400
The request was invalid or cannot be otherwise served. An accompanying
error message will explain further. In API v1.1, requests without
authentication are considered invalid and will yield this response.
Http Status code
401
Authentication credentials were missing or incorrect.
Http Status code
403
The request is understood, but it has been refused or access is not
allowed. An accompanying error message will explain why. This code is
used when requests are being denied due to update limits.
Http Status code
404
The URI requested is invalid or the resource requested, such as a user,
does not exists. Also returned when the requested format is not supported
by the requested method.
Http Status code
406
Returned by the Search API when an invalid format is specified in the
request.
Http Status code
410
This resource is gone. Used to indicate that an API endpoint has been
turned off. For example: "The Twitter REST API v1 will soon stop
functioning. Please migrate to API v1.1."
Http Status code
420
Returned by the version 1 Search and Trends APIs when you are being rate
limited.
Http Status code
422
Returned when an image uploaded to POST account/update_profile_banner is
unable to be processed.
Http Status code
429
Returned in API v1.1 when a request cannot be served due to the
application's rate limit having been exhausted for the resource. See Rate
Limiting in API v1.1.
Http Status code
500
Something is broken. Please post to the group so the Twitter team can
investigate.
Http Status code
502
Twitter is down or being upgraded.
Http Status code
503
The Twitter servers are up, but overloaded with requests. Try again later.
Http Status code
504
The Twitter servers are up, but the request couldn't be serviced due to
some failure within our stack. Try again later.