Integration Guide

Key concepts and best practices for integrating mutes endpoints

This guide covers the key concepts you need to integrate the mutes endpoints into your application.

---

Authentication

Mutes endpoints require user authentication to access private mute lists:

Method	Description
OAuth 2.0 Authorization Code with PKCE	Recommended for new applications
OAuth 1.0a User Context	Legacy support

App-Only authentication is not supported. You must authenticate on behalf of a user.

Required scopes (OAuth 2.0)

Scope	Required for
mute.read	Retrieving muted accounts
mute.write	Muting and unmuting accounts
users.read	Required with mute scopes

---

Endpoints overview

Method	Endpoint	Description
GET	/2/users/:id/muting	Get list of muted accounts
POST	/2/users/:id/muting	Mute an account
DELETE	/2/users/:source_user_id/muting/:target_user_id	Unmute an account

---

Fields and expansions

Default response

{
  "data": [
    {
      "id": "1234567890",
      "name": "Example User",
      "username": "example"
    }
  ]
}

Available fields

user.fields

Field	Description
created_at	Account creation date
description	User bio
profile_image_url	Avatar URL
public_metrics	Follower/following counts
verified	Verification status

expansions

Expansion	Description
pinned_tweet_id	User’s pinned Post

Example with fields

cURL

shellscript

curl "https://api.x.com/2/users/123456789/muting?\
user.fields=username,verified,created_at&\
max_results=100" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

---

Pagination

For users with large mute lists, results are paginated:

cURL

shellscript

# First request
curl "https://api.x.com/2/users/123/muting?max_results=100" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

# Subsequent request with pagination token
curl "https://api.x.com/2/users/123/muting?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

Pagination guide

Learn more about pagination

---

Behavior differences

Muting vs Blocking

Feature	Mute	Block
See their Posts	No (hidden)	No
They see your Posts	Yes	No
They follow you	Yes (can follow)	No (removed)
They can DM you	Yes	No
Notification sent	No	No

Muting is private — the muted user is not notified and cannot tell they’ve been muted.

---

Error handling

Status	Error	Solution
400	Invalid request	Check user ID format
401	Unauthorized	Verify access token
403	Forbidden	Check scopes and permissions
404	Not Found	User doesn’t exist
429	Too Many Requests	Wait and retry

---

Next steps

Quickstart

Make your first mutes request

Blocks

Block users instead of muting

API Reference

Full endpoint documentation

Sample code

Working code examples