Mutes

​

Introduction

Muting an account allows you to remove an account’s Posts from your timeline without unfollowing or blocking that account. Muted accounts will not know that you’ve muted them and you can unmute them at any time. With manage mutes endpoints, developers can create safer experiences for people on X. One example of how to build with manage mutes is an application that allows you to mute accounts that might Post about specific topics for a specified length of time. With the mutes lookup endpoint, you can see who you or an authenticated user has muted. This can be useful to determine how you interact with the muted accounts. 

Since you are making requests for private information with mute lookup, and on behalf of a user with manage mutes, you must authenticate these endpoints with either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, and use the user Access Tokens associated with a user that has authorized your App, which can be generated using the 3-legged OAuth flow (OAuth 1.0a) or the Authorization Code with PKCE grant flow) (OAuth 2.0).

​

Mutes lookup

The mutes lookup endpoint allows you to see which accounts the authenticated user has muted. This endpoint has a rate limit of 15 requests per 15 minutes per user.

​

Manage mutes

The manage mute endpoints enable you to mute or unmute a specified account on behalf of an authenticated user. For these endpoints, there are two methods available: POST and DELETE. The POST method allows you to mute an account, and the DELETE method allows you to unmute an account. There is a user rate limit of 50 requests per 15 minutes for both the POST and DELETE endpoints.

**Please note: **If a user mutes from X, there is a limit of 200 requests per 15 minutes.

Account setup

To access these endpoints, you will need:

• An approved developer account.
• To authenticate using the keys and tokens from a developer App that is located within a Project. 

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

​

Getting started with the mutes lookup endpoint

This quick start guide will help you make your first request to the mutes lookup endpoint using Postman.

Please visit our X API v2 sample code GitHub repository if you want to see sample code in different languages.

​

Steps to build a mutes lookup 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 will 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 “Mutes” folder, and select “Mutes lookup”.  

​

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 a user

With this endpoint, you must specify your user ID or the ID of an authenticated user to see who you or the authenticated user has muted.

In Postman, navigate to the “Params” tab and enter the authenticated user ID into the “Value” column of the id under “Path Variables” (at the bottom of the section), making sure to not include any spaces before or after ID.

Above the “Path Variables” section, you’ll notice there are optional “Query Params” to add. For this example, we will check the variable max_results and add a value of 5.

​

Step four: Identify and specify which fields you would like to retrieve

If you click the “Send” button after step three, you will receive the default user object fields in your response: id, name, and username.

If you want to receive additional fields beyond id, name, and username, you will have to specify those fields in your request with the fields and/or expansions parameters.

For this exercise, we will request three additional sets of fields from different objects:

1. The additional user.created_at field in the primary user objects.
2. The associated pinned Posts’ object’s default fields for the returned users: id and text.
3. The additional  tweet.created_at field in the associated Post objects.

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see a similar URL with your own user ID instead of the example ID URL next to the “Send” button:

https://api.x.com/2/users/1324848235714736129/muting?user.fields=created_at&expansions=pinned_tweet_id&tweet.fields=created_at&max_results=5

​

Step five: Make your request and review your response

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

{
  "data": [
    {
      "username": "TwitterDev",
      "created_at": "2013-12-14T04:35:55.000Z",
      "id": "2244994945",
      "name": "Twitter Dev",
      "pinned_tweet_id": "1430984356139470849"
    }
  ],
  "includes": {
    "tweets": [
      {
        "created_at": "2021-08-26T20:03:51.000Z",
        "id": "1430984356139470849",
        "text": "Help us build a better Twitter Developer Platform!\n \nTake the annual developer survey >>> https://t.co/9yTbEKlJHH https://t.co/fYIwKPzqua"
      }
    ]
  },
  "meta": {
    "result_count": 1
  }
}

​

Step six: Paginate through your results

You may notice that there is a meta object located at the bottom of the response. If you received a next_token, this signals that there is another page of results that we can retrieve. To pull the next page of results, you will pull the value of the next_token field and add it to the request as the value to an additional pagination_token query parameter.  

If you send the request after adding this additional parameter, the next five results will be delivered with the subsequent payload since we specified max_results as 5 in step three. You can continue to repeat this process until all results have been returned, but you can also use the max_results parameter to request up to 1000 users per request, so you don’t have to paginate through results quite as much.

​

Getting started with the manage mutes endpoints

This quick start guide will help you make your first request to the manage mutes 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 mutes 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 will 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 “Mutes” folder, and select “Mute a user’s 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 mute whom

Manage mutes endpoints require two IDs: one for the user (the user who wishes to mute or unmute another user) and the target user (the user that will be muted or unmuted). The user’s ID must correspond to the authenticating user’s ID, meaning that you must pass the Access Tokens associated with the user ID when authenticating your request. 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. 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 ID of the user you wish to mute as the value for the target_user_id parameter. Be sure not to include any spaces before or after any ID.

​

Step four: Make your request and review your response

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

{ "data": { "muting": true } }

If you receive a “muting”: true, then the id is successfully muting the target_user_id

To unmute the same user you can use the request entitled “Unmute a user ID”, which is also found in the “Mutes” folder of the X API v2 collection loaded in Postman. The source_user_id should be your user ID and target_user_id should be the user ID to unmute. You will not have to add this as a JSON body so you will want to make sure that you add in the requisite query params for source_user_id and target_user_id.

On a successful unmute, you will receive a similar response to the following example:

{ "data": { "muting": false } }

​

Integration guide

This page contains information on several tools and key concepts that you should be aware of as you integrate the mutes endpoints into your system. We’ve broken the page into a couple of different sections:

• Helpful tools
• Key Concepts
• Authentication
• Developer portal, Projects, and Apps
• Rate limits
• Fields and expansions
• Pagination

​

Helpful tools

Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with:

​

Postman

Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our “Using Postman” page. 

​

Code samples

Interested in getting set up with this endpoint with some code in your preferred coding language? We’ve got a handful of different code samples available that you can use as a starting point on our Github page.

​

Third-party libraries

Take advantage of one of our communities’ third-party libraries to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag.

​

Key concepts

​

Authentication

All X API v2 endpoints require you to authenticate your requests with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, or OAuth 2.0 Authorization Code with PKCE to authenticate your requests to these endpoints. 

OAuth 1.0a User Context requires you to utilize your API Keys, user Access Tokens, and a handful of other parameters to create an authorization header, which you will then pass with your request. The Access Tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the 3-legged OAuth flow. 

Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a library, use a tool like Postman, or use OAuth 2.0 to authenticate your requests.

OAuth 2.0 Authorization Code with PKCE allows for greater control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. 

To enable OAuth 2.0 in your App, you must enable it in your’s App’s authentication settings found in the App settings section of the developer portal.

​

Developer portal, Projects, and developer Apps

To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must sign up for a developer account, set up a Project within that account, and created a developer App within that Project. You can then find your keys and tokens within your developer App.  

​

Rate limits

Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, rate limits are placed on each endpoint that limits the number of requests you can make on behalf of your app or on behalf of an authenticated user. 

These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App.

There is a user rate limit of 50 requests per 15 minutes per endpoint with both POST and DELETE methods. However, with the GET method, the rate limit is only 15 requests per 15 minutes.  

​

Fields and expansions

The X API v2 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called fields and expansions. The expansions parameter allows you to expand objects referenced in the payload. For example, this endpoint allows you to pull the following expansions:

• pinned_tweet_id

The fields parameter allows you to select exactly which fields within the different data objects you would like to receive. This endpoint delivers User objects primarily. By default, the User object returns the id , name  and username fields. To receive additional fields such as user.created_at or user.entities, you will have to specifically request those using a fields parameter. 

We’ve added a guide on using fields and expansions together to our X API v2 data dictionary.

​

Pagination

Mutes lookup can return a lot of data. To ensure we are returning consistent, high-performing results at any given time, we use pagination. Pagination is a feature in X API v2 endpoints that return more results than can be returned in a single response. When that happens, the data is returned in a series of ‘pages’. Learn more about how to paginate through results.

​

Comparing X API’s mutes endpoints

​

Mutes lookup

The v2 mutes lookup endpoint will replace the standard v1.1 GET mutes/users/ids and GET mutes/users/list endpoints.

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

​

Manage mutes

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

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

Mute a user

Unmute a user

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

Other migration resources

Manage mutes: Standard v1.1 to X API v2

X API migration hub

​

Mutes lookup: Standard v1.1 compared to X API v2

If you have been working with the standard v1.1 GET mutes/users/ids and GET mutes/users/list endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 mutes lookup endpoints.

• Similarities
  • Authentication
• Differences

  • Endpoint URLs

  • Users per request limits

  • App and Project requirements

  • Response data formats

  • Request parameters

​

Similarities

Authentication

Both the standard v1.1 and X API v2 mutes lookup endpoints use OAuth 1.0a User Context. Therefore, if you were previously using one of the standard v1.1 mutes lookup 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:
  • GET https://api.x.com/1.1/mutes/users/ids.json (list of user IDs who the specified user muted)
  • GET https://api.x.com/1.1/mutes/users/lists.json (list of users who are muted by the specified user)
• X API v2 endpoint:
  • GET https://api.x.com/2/users/:id/muting (list of users who are muted by the specified user ID)  

Users per request limits

The standard v1.1 endpoints allow you to return up to 5000 users per request. The new v2 endpoints allow you to return up to 1000 users per request. To return a full 1000 users, you will need to pass max_results=1000 as a query parameter; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request.  

App and Project requirements

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

Response data format

One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload.

For the standard endpoints, you receive many of the response fields by default and then have the option to use parameters to identify which fields or sets of fields should return in the payload.

The X API v2 version only delivers the user id, name, and username fields by default. To request any additional fields or objects, you will need to use the fields and expansions parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object. 

We encourage you to read more about these new parameters in their respective guides, or by reading our guide on how to use fields and expansions. 

We have also put together a data format migration guide which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.   

In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and user objects.

• At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array. 
• Instead of referring to Retweeted and Quoted “statuses”, X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. 
• Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like. 
• X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.   

We also introduced a new set of fields to the Post object including the following:

• A conversation_id field
• Two new annotations fields, including context and entities
• Several new metrics fields 
• A new reply_setting field, which shows you who can reply to a given Post

Request parameters

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

There are also a set of standard v1.1 Mutes lookup request parameters not supported in X API v2:

​

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

If you have been working with the standard v1.1 POST mutes/users/create and POST mutes/users/destroy endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage mutes 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 mutes 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/mutes/users/create.json (mute a user)
  • POST https://api.x.com/1.1/mutes/users/destroy.json (unmute a user)
• X API v2 endpoint:
  • POST https://api.x.com/2/users/:id/muting (mute a user)
  • DELETE https://api.x.com/2/users/:source\_user\_id/muting/:target\_user\_id (unmute a user) 

App and Project requirements

The X API v2 endpoints require that you use credentials from a developer App that is associated with 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, an id of the user muting a target user is 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 mute/unmute. 

​

API reference index

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

​

Mutes lookup

​

Manage mutes

​

GET /2/users/:id/muting

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

​

Endpoint URL

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

​

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 getMutedUsers = await twitterClient.users.usersIdMuting(
      //The ID of the user for whom to return results
      "2244994945"
    );
    console.dir(getMutedUsers, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": [
    {
      "id": "2244994945",
      "name": "Twitter Dev",
      "username": "TwitterDev"
    }
  ],
  "meta": {
    "result_count": 1
  }
}

​

Response fields

​

POST /2/users/:id/muting

Allows an authenticated user ID to mute the target user.

​

Endpoint URL

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

​

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 muteUser = await twitterClient.users.usersIdMute(
      //The ID of the user that is requesting to mute the target user
      "6253282",
      {
        //The ID of the user that the source user is requesting to mute
        target_user_id: "2244994945",
      }
    );
    console.dir(muteUser, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response

{
  "data": {
    "muting": true
  }
}

​

Response fields

​

DELETE /2/users/:source_user_id/muting/:target_user_id

Allows an authenticated user ID to unmute the target user.

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

​

Endpoint URL

https://api.x.com/2/users/:source_user_id/muting/: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 unmuteUser = await twitterClient.users.usersIdUnmute(
      //The ID of the user that is requesting to unmute the target user
      "2244994945",

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

​

Example responses

• Successful response

{
  "data": {
    "muting": false
  }
}

​

Response fields