GET /2/users/:id/following

Returns a list of users the specified user ID is following.



Endpoint URL

https://api.twitter.com/2/users/:id/following

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Bearer token

OAuth 1.0a User context

Rate limit

15 requests per 15-minute window (app auth)

15 requests per 15-minute window (user auth)

Learn more about rate limits.



Path parameters

NameTypeDescription
id
 Required 
stringThe user ID whose following you would like to retrieve.


Query parameters

NameTypeDescription
expansions
 Optional 
enum (pinned_tweet_id)Comma-separated list of expansions. Expansions enable requests to expand an ID into a full object in the includes response object. Make sure to not include a space between commas and fields.
max_results
 Optional 
integerThe maximum number of results to be returned per page. This can be a number between 1 and the 1000. By default, each page will return 100 results.
pagination_token
 Optional 
stringUsed to request the next page of results if all results weren't returned with the latest request, or to go back to the previous page of results. To return the next page, pass the next_token returned in your previous response. To go back one page, pass the previous_token returned in your previous response.
tweet.fields
 Optional 
enum (attachments, author_id, context_annotations, conversation_id, created_at, entities, geo, id, in_reply_to_user_id, lang, non_public_metrics, public_metrics, organic_metrics, promoted_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld)Comma-separated list of additional fields to return in the Tweet object. By default, the endpoint only returns id and text. Make sure to not include a space between commas and fields.
user.fields
 Optional 
enum (created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld)Comma-separated list of additional fields to return in the user object. By default, the endpoint does not return any user field. To use this parameter, you must include the author_id expansion parameter in the request. Make sure to not include a space between commas and fields.


Example requests

  • cURL (default fields)
  • cURL (optional fields)
curl https://api.twitter.com/2/users/2244994945/following?max_results=10 -H "Authorization: Bearer $BEARER_TOKEN"
# Returns the list of users TwitterDev is following, including the a pinned Tweet and Tweet annotations for that Tweet (when available)
 curl "https://api.twitter.com/2/users/2244994945/following?expansions=pinned_tweet_id,context_annotations&user.fields=created_at&tweet.fields=created_at&max_results=10" -H "Authorization: Bearer $BEARER_TOKEN"

Example responses

  • Default fields
  • Optional fields
{
  "data": [
    {
      "id": "6253282",
      "name": "Twitter API",
      "username": "TwitterAPI"
    },
    {
      "id": "2244994945",
      "name": "Twitter Dev",
      "username": "TwitterDev"
    },
    {
      "id": "783214",
      "name": "Twitter",
      "username": "Twitter"
    },
    {
      "id": "95731075",
      "name": "Twitter Safety",
      "username": "TwitterSafety"
    },
    {
      "id": "3260518932",
      "name": "Twitter Moments",
      "username": "TwitterMoments"
    },
    {
      "id": "373471064",
      "name": "Twitter Music",
      "username": "TwitterMusic"
    },
    {
      "id": "791978718",
      "name": "Twitter Official Partner",
      "username": "OfficialPartner"
    },
    {
      "id": "17874544",
      "name": "Twitter Support",
      "username": "TwitterSupport"
    },
    {
      "id": "234489024",
      "name": "Twitter Comms",
      "username": "TwitterComms"
    },
    {
      "id": "1526228120",
      "name": "Twitter Data",
      "username": "TwitterData"
    }
  ],
  "meta": {
    "result_count": 10,
    "next_token": "DFEDBNRFT3MHCZZZ"
  }
}
{
  "data": [
    {
      "pinned_tweet_id": "1293595870563381249",
      "id": "6253282",
      "username": "TwitterAPI",
      "name": "Twitter API"
    },
    {
      "pinned_tweet_id": "1293593516040269825",
      "id": "2244994945",
      "username": "TwitterDev",
      "name": "Twitter Dev"
    },
    {
      "id": "783214",
      "username": "Twitter",
      "name": "Twitter"
    },
    {
      "pinned_tweet_id": "1271186240323432452",
      "id": "95731075",
      "username": "TwitterSafety",
      "name": "Twitter Safety"
    },
    {
      "id": "3260518932",
      "username": "TwitterMoments",
      "name": "Twitter Moments"
    },
    {
      "pinned_tweet_id": "1293216056274759680",
      "id": "373471064",
      "username": "TwitterMusic",
      "name": "Twitter Music"
    },
    {
      "id": "791978718",
      "username": "OfficialPartner",
      "name": "Twitter Official Partner"
    },
    {
      "pinned_tweet_id": "1289000334497439744",
      "id": "17874544",
      "username": "TwitterSupport",
      "name": "Twitter Support"
    },
    {
      "pinned_tweet_id": "1283543147444711424",
      "id": "234489024",
      "username": "TwitterComms",
      "name": "Twitter Comms"
    },
    {
      "id": "1526228120",
      "username": "TwitterData",
      "name": "Twitter Data"
    }
  ],
  "includes": {
    "tweets": [
      {
        "context_annotations": [
          {
            "domain": {
              "id": "46",
              "name": "Brand Category",
              "description": "Categories within Brand Verticals that narrow down the scope of Brands"
            },
            "entity": {
              "id": "781974596752842752",
              "name": "Services"
            }
          },
          {
            "domain": {
              "id": "47",
              "name": "Brand",
              "description": "Brands and Companies"
            },
            "entity": {
              "id": "10045225402",
              "name": "Twitter"
            }
          },
          {
            "domain": {
              "id": "65",
              "name": "Interests and Hobbies Vertical",
              "description": "Top level interests and hobbies groupings, like Food or Travel"
            },
            "entity": {
              "id": "848920371311001600",
              "name": "Technology",
              "description": "Technology and computing"
            }
          },
          {
            "domain": {
              "id": "66",
              "name": "Interests and Hobbies Category",
              "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations"
            },
            "entity": {
              "id": "848921413196984320",
              "name": "Computer programming",
              "description": "Computer programming"
            }
          },
          {
            "domain": {
              "id": "47",
              "name": "Brand",
              "description": "Brands and Companies"
            },
            "entity": {
              "id": "10045225402",
              "name": "Twitter"
            }
          }
        ],
        "id": "1293595870563381249",
        "text": "Twitter API v2: Early Access released\n\nToday we announced Early Access to the first endpoints of the new Twitter API!\n\n#TwitterAPI #EarlyAccess #VersionBump https://t.co/g7v3aeIbtQ"
      },
      {
        "context_annotations": [
          {
            "domain": {
              "id": "46",
              "name": "Brand Category",
              "description": "Categories within Brand Verticals that narrow down the scope of Brands"
            },
            "entity": {
              "id": "781974596752842752",
              "name": "Services"
            }
          },
          {
            "domain": {
              "id": "47",
              "name": "Brand",
              "description": "Brands and Companies"
            },
            "entity": {
              "id": "10045225402",
              "name": "Twitter"
            }
          },
          {
            "domain": {
              "id": "65",
              "name": "Interests and Hobbies Vertical",
              "description": "Top level interests and hobbies groupings, like Food or Travel"
            },
            "entity": {
              "id": "848920371311001600",
              "name": "Technology",
              "description": "Technology and computing"
            }
          },
          {
            "domain": {
              "id": "66",
              "name": "Interests and Hobbies Category",
              "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations"
            },
            "entity": {
              "id": "848921413196984320",
              "name": "Computer programming",
              "description": "Computer programming"
            }
          }
        ],
        "id": "1293593516040269825",
        "text": "It’s finally here! 🥁 Say hello to the new #TwitterAPI.\n\nWe’re rebuilding the Twitter API v2 from the ground up to better serve our developer community. And today’s launch is only the beginning.\n\nhttps://t.co/32VrwpGaJw https://t.co/KaFSbjWUA8"
      },
      {
        "id": "1271186240323432452",
        "text": "We’re disclosing new state-linked information operations to our public archive — the only one of its kind in the industry. Originating from the People’s Republic of China (PRC), Russia, and Turkey, all associated accounts and content have been removed. https://t.co/obRqr96iYm"
      },
      {
        "id": "1293216056274759680",
        "text": "say howdy to your new yeehaw king @orvillepeck—our #ArtistToFollow this month 🤠 https://t.co/3pk9fYcPHb"
      },
      {
        "context_annotations": [
          {
            "domain": {
              "id": "46",
              "name": "Brand Category",
              "description": "Categories within Brand Verticals that narrow down the scope of Brands"
            },
            "entity": {
              "id": "781974596752842752",
              "name": "Services"
            }
          },
          {
            "domain": {
              "id": "47",
              "name": "Brand",
              "description": "Brands and Companies"
            },
            "entity": {
              "id": "10045225402",
              "name": "Twitter"
            }
          }
        ],
        "id": "1289000334497439744",
        "text": "We’ve significantly limited access to our internal tools and systems. Until we can safely resume normal operations, our response times to some support needs and reports will be slower. Thank you for your patience as we work through this."
      },
      {
        "context_annotations": [
          {
            "domain": {
              "id": "46",
              "name": "Brand Category",
              "description": "Categories within Brand Verticals that narrow down the scope of Brands"
            },
            "entity": {
              "id": "781974596752842752",
              "name": "Services"
            }
          },
          {
            "domain": {
              "id": "47",
              "name": "Brand",
              "description": "Brands and Companies"
            },
            "entity": {
              "id": "10045225402",
              "name": "Twitter"
            }
          }
        ],
        "id": "1283543147444711424",
        "text": "Follow @TwitterSupport for the latest on the security incident ⬇️ https://t.co/7FKKksJqxV"
      }
    ],
    "meta": {
      "result_count": 10,
      "next_token": "DFEDBNRFT3MHCZZZ"
    }
  }
}

Response fields

NameTypeDescription
id
 Default 
stringUnique identifier of this user. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
name
 Default 
stringThe friendly name of this user, as shown on their profile.
username
 Default 
stringThe Twitter handle (screen name) of this user.
created_atdate (ISO 8601)Creation time of this account.

To return this field, add user.fields=created_at in the request's query parameter.
protectedbooleanIndicates if this user has chosen to protect their Tweets (in other words, if this user's Tweets are private).

To return this field, add user.fields=protected in the request's query parameter.
withheldobjectContains withholding details for withheld content.

To return this field, add user.fields=withheld in the request's query parameter.
withheld.country_codesarrayProvides a list of countries where this user is not available.

To return this field, add user.fields=withheld.country_codes in the request's query parameter.
withheld.scopeenum (tweet, user)Indicates whether the content being withheld is a Tweet or a user (this API will return user).

To return this field, add user.fields=withheld.scope in the request's query parameter.
locationstringThe location specified in the user's profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.

To return this field, add user.fields=location in the request's query parameter.
urlstringThe URL specified in the user's profile, if present.

To return this field, add user.fields=url in the request's query parameter.
descriptionstringThe text of this user's profile description (also known as bio), if the user provided one.

To return this field, add user.fields=description in the request's query parameter.
verifiedbooleanIndicate if this user is a verified Twitter user.

To return this field, add user.fields=verified in the request's query parameter.
entitiesobjectThis object and its children fields contain details about text that has a special meaning in the user's description.

To return this field, add user.fields=entities in the request's query parameter.
entities.urlarrayContains details about the user's profile website.
entities.url.urlsarrayContains details about the user's profile website.
entities.url.urls.startintegerThe start position (zero-based) of the recognized user's profile website.
entities.url.urls.endintegerThe end position (zero-based) of the recognized user's profile website.
entities.url.urls.urlstringThe URL in the format entered by the user.
entities.url.urls.expanded_urlstringThe fully resolved URL.
entities.url.urls.display_urlstringThe URL as displayed in the user's profile.
entities.descriptionarrayContains details about URLs, Hashtags, Cashtags, or mentions located within a user's description.
entities.description.urlsarrayContains details about any URLs included in the user's description.
entities.description.urls.startintegerThe start position (zero-based) of the recognized URL in the user's description.
entities.description.urls.endintegerThe end position (zero-based) of the recognized URL in the user's description.
entities.description.urls.urlstringThe URL in the format entered by the user.
entities.description.urls.expanded_urlstringThe fully resolved URL.
entities.description.urls.display_urlstringThe URL as displayed in the user's description.
entities.description.hashtagsarrayContains details about text recognized as a Hashtag.
entities.description.hashtags.startintegerThe start position (zero-based) of the recognized Hashtag within the Tweet.
entities.description.hashtags.endintegerThe end position (zero-based) of the recognized Hashtag within the Tweet.
entities.description.hashtags.hashtagstringThe text of the Hashtag.
entities.description.mentionsarrayContains details about text recognized as a user mention.
entities.description.mentions.startintegerThe start position (zero-based) of the recognized user mention within the Tweet.
entities.description.mentions.endintegerThe end position (zero-based) of the recognized user mention within the Tweet.
entities.description.mentions.usernamestringThe part of text recognized as a user mention.
entities.description.cashtagsarrayContains details about text recognized as a Cashtag.
entities.description.cashtags.startintegerThe start position (zero-based) of the recognized Cashtag within the Tweet.
entities.description.cashtags.endintegerThe end position (zero-based) of the recognized Cashtag within the Tweet.
entities.description.cashtags.cashtagstringThe text of the Cashtag.
profile_image_urlstringThe URL to the profile image for this user, as shown on the user's profile.
public_metricsobjectContains details about activity for this user.
public_metrics.followers_countintegerNumber of users who follow this user.
public_metrics.following_countintegerNumber of users this user is following.
public_metrics.tweet_countintegerNumber of Tweets (including Retweets) posted by this user.
public_metrics.listed_countintegerNumber of lists that include this user.
pinned_tweet_idstringUnique identifier of this user's pinned Tweet.

You can obtain the expanded object in includes.tweets by adding expansions=pinned_tweet_id in the request's query parameter.
includes.tweetsarrayWhen including the expansions=pinned_tweet_id parameter, this includes the pinned Tweets attached to the returned users' profiles in the form of Tweet objects with their default fields and any additional fields requested using the tweet.fields parameter, assuming there is a referenced Tweet present in the returned Tweet(s).
errorsobjectContains details about errors that affected any of the requested users. See Status codes and error messages for more details.
meta
 Default 
objectThis object contains information about the number of users returned in the current request, and pagination details.
meta.result_count
 Default 
integerThe number of users returned in this request. Note that this number may be lower than what was specified in the max_results query parameter.
meta.previous_tokenstringPagination token for the previous page of results. This value is returned when there are multiple pages of results, as the current request may only return a subset of results. To go back to the previous page, passing the value from this field in the pagination_token query parameter. When this field is not returned in the response, it means you are on the first page of results.
meta.next_tokenstringPagination token for the next page of results. This value is returned when there are multiple pages of results, as the current request may only return a subset of results. To retrieve the full list, keep passing the value from this field in the pagination_token query parameter. When this field is not returned in the response, it means you've reached the last page of results, and that there are no further pages.

Was this document helpful?

Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.