Integration Guide

This guide covers the key concepts you need to integrate the mutes endpoints into your application. Reference for the X API v2 standard tier covering mutes.

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"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Get muted users with additional fields
for page in client.users.get_muting(
    user_id="123456789",
    user_fields=["username", "verified", "created_at"],
    max_results=100
):
    for user in page.data:
        print(f"{user.username} - Verified: {user.verified}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const paginator = client.users.getMuting("123456789", {
  userFields: ["username", "verified", "created_at"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((user) => {
    console.log(`${user.username} - Verified: ${user.verified}`);
  });
}

---

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"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# The SDK handles pagination automatically
all_muted = []

for page in client.users.get_muting(user_id="123", max_results=100):
    if page.data:
        all_muted.extend(page.data)

print(f"Muted {len(all_muted)} users")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

async function getAllMutedUsers(userId) {
  const allMuted = [];

  // The SDK handles pagination automatically
  const paginator = client.users.getMuting(userId, { maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allMuted.push(...page.data);
    }
  }

  return allMuted;
}

// Usage
const muted = await getAllMutedUsers("123");
console.log(`Muted ${muted.length} users`);

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