Follows

​

Introduction

We offer two sets of endpoint groups to help you lookup, create, and delete follow relationships: follows lookup and manage follows.  

​

Follows lookup

Only available to those with Enterprise access

The follows lookup endpoints enable you to explore and analyze relationships between users, which is sometimes called network analysis. Specifically, there are two REST endpoints that return user objects representing who a specified user is following, or who is following a specified user.

You can authenticate this endpoint with either OAuth 1.0a User Context, [App only](https://developer.twitter.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token), or OAuth 2.0 Authorization Code with PKCE. You can request up to 1,000 users per request, and pagination tokens will be provided for paging through large sets of results.  

​

Manage follows

The manage follows endpoints enable you to follow or unfollow users.

Since you are making requests on behalf of a user, you must authenticate these endpoints with either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, and utilize the user Access Tokens associated with the user you are making the request on behalf of. You can generate this user Access Token using the 3-legged OAuth flow (OAuth 1.0a) or using the Authorization Code with PKCE grant flow) (OAuth 2.0).

You are limited to 400 follow actions per day on behalf of each authenticated user, and will be limited to 1,000 actions per day per App across all of your authenticated users. For example, if you have five authenticated users, you can follow 400 users per day (per user limit) with two of those users for a total of 800 actions, and will have to split the remaining 200 actions (per app) amongst the remaining three users. This limit does not apply to the unfollow endpoint, which has a separate limit of 500 actions per day (per app).

Learn more about getting access to the X API v2 endpoints in our getting started guide.

​

Getting started with the manage follows endpoints

This quick start guide will help you make your first request to the manage follows endpoints using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. 

​

Steps to build a manage follows request

​

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load the X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the “Follows” folder, and select “Follow a user ID”.  

​

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do so with this endpoint, you must authenticate your request using either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE.

In this example, we are going to use OAuth 1.0a User Context.

You must add your keys and tokens – specifically your API Key, API Secret Key, OAuth 1.0a user Access Token, and OAuth 1.0a user Access Token Secret – to Postman. You can do this by selecting the environment named “X API v2” in the top-right corner of Postman and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

These variables will automatically be pulled into the request’s authorization tab if you’ve done this correctly.  

​

Step three: Specify who is going to follow whom

Manage follows endpoints take two IDs: one for the source user (the user who wishes to follow or unfollow another user) and the target user (the user that will be followed or unfollowed). The source user’s ID must correspond to the user ID of the authenticating user. In this case, you can specify the ID belonging to your own user. You can find your ID in two ways:

1. Using the user lookup by username endpoint, you can pass a username and receive the id field. 
2. Looking at your Access Token, you will find that the numeric part is your user ID.  

The target ID can be any valid user ID. For example the user ID for @XDevelopers is 2244994945.

In Postman, navigate to the “Params” tab, and enter your ID into the “Value” column of the id path variable. Navigate to the “Body” tab and and 2244994945 (the user ID for @XDevelopers) as the value for the target_user_id parameter. Making sure to not include any spaces before or after any ID.

If you click the “Send” button, you will receive a response object containing the status of the relationship:

• If you receive a “following”: true, then the id is successfully following the target_user_id.
• If you receive a “pending”: true, then the target_user_id is protected and must accept your follow request.

​

Step four: Make your request and review your response

Once you have everything set up, hit the “Send” button and you will receive the following response:

    "data": {
        "following": true,
        "pending_follow": false
    }
}

Similarly, if you were trying to unfollow a user, you would use the “Unfollow a user ID” request within the same Postman collection. However, both the source_user_id and target_user_id parameters should be passed as path variables using the unfollow endpoint. 

​

Comparing X API’s follows endpoints

​

Follows lookup

The v2 follows lookup endpoints will replace the standard v1.1 followers/ids, v1.1 followers/list, v1.1 friends/ids, and v1.1 friends/list endpoints.

The following tables compare the various types of follows lookup endpoints:

​

Manage follows

The v2 manage follows endpoints will replace the standard v1.1 POST friendships/create and POST friendships/destroy endpoints.

The following tables compare the standard v1.1 and X API v2 create follow endpoints:

​

Follow a user

​

Unfollow a user

The following tables compare the standard v1.1 and X API v2 delete follow endpoints:

Other migration resources

Follows lookup: Standard v1.1 to X API v2

Manage follows: Standard v1.1 to X API v2

X API migration hub

​

Manage follows: Standard v1.1 compared to X API v2

If you have been working with the standard v1.1 POST friendships/create and POST friendships/destroy endpoints, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 manage follows endpoints.

• Similarities
  • OAuth 1.0a User Context
• Differences

  • Endpoint URLs

  • App and Project requirements

  • HTTP methods

  • Request parameters

     

​

Similarities

OAuth 1.0a User Context authentication method

Both the endpoint versions support OAuth 1.0a User Context. Therefore, if you were previously using one of the standard v1.1 manage follows endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. 

​

Differences

Endpoint URLs

• Standard v1.1 endpoints:
  • POST https://api.x.com/1.1/friendships/create.json (follow a user)
  • POST https://api.x.com/1.1/friendships/destroy.json (unfollow a user)
• X API v2 endpoint:
  • POST https://api.x.com/2/users/:id/following (follow a user)
  • DELETE https://api.x.com/2/users/:source\_user\_id/following/:target\_user\_id (unfollow a user) 

App and Project requirements

The X API v2 endpoints require that you use credentials from a developer App that is associated to a Project when authenticating your requests. All X API v1.1 endpoints can use credentials from standalone Apps or Apps associated with a project.

Request parameters

The following standard v1.1 request parameters have equivalents in X API v2:

Please note that the Standard v1.1 parameters are passed as query parameters, whereas the X API v2 parameters are passed as body parameters (for the POST endpoint) or path parameters (for the DELETE endpoint).

Also, the v2 id and source_user_id are not required when using the standard v1.1 endpoints since the Access Tokens passed with OAuth 1.0a User Context inferred which user was initiating the follow/unfollow. 

​

API reference index

For the complete API reference, select an endpoint from the list:

​

Manage follows

​

POST /2/users/:id/following

Allows a user ID to follow another user.

If the target user does not have public Tweets, this endpoint will send a follow request.

The request succeeds with no action when the authenticated user sends a request to a user they’re already following, or if they’re sending a follower request to a user that does not have public Tweets.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

JSON body parameters

​

Example code with offical SDKs

• TypeScript
• Java

(async () => {
  try {
    const followUser = await twitterClient.users.usersIdFollow(
      //The ID of the user that is requesting to follow the target user
      "6253282",
      {
        //The ID of the user that the source user is requesting to follow
        target_user_id: "2244994945",
      }
    );
    console.dir(followUser, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response (public user)
• Successful response (protected user)

{
  "data": {
    "following": true,
    "pending_follow": false
  }
}

​

Response fields

​

DELETE /2/users/:source_user_id/following/:target_user_id

Allows a user ID to unfollow another user.

The request succeeds with no action when the authenticated user sends a request to a user they’re not following or have already unfollowed.

​

Endpoint URL

https://api.x.com/2/users/:source_user_id/following/:target_user_id

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Example code with offical SDKs

• TypeScript
• Java

(async () => {
  try {
    const unfollowUser = await twitterClient.users.usersIdUnfollow(
      //The ID of the user that is requesting to unfollow the target user
      "2244994945",

      //The ID of the user that the source user is requesting to unfollow
      "6253282"
    );
    console.dir(unfollowUser, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response

{
  "data": {
    "following": false
  }
}

​

Response fields

​

GET /2/users/:id/followers

Returns a list of users who are followers of the specified user ID.

​

Endpoint URL

https://api.x.com/2/users/:id/followers

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const getUsersFollowers = await twitterClient.users.usersIdFollowers(
      //The ID of the user for whom to return results
      "2244994945"
    );
    console.dir(getUsersFollowers, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

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"
  }
}

​

Response fields