Quickstart

This guide walks you through retrieving your block list, as well as blocking and unblocking users. Reference for the X API v2 standard tier covering blocks.

This guide walks you through retrieving your block list, as well as blocking and unblocking users.

The block and unblock users endpoints are only available under the Enterprise plan. You can fill out the Enterprise interest form here.

Prerequisites

Before you begin, you’ll need:

• A developer account with an approved App
• User Access Token (OAuth 1.0a or OAuth 2.0 PKCE)

---

Get blocked users

1. Get your user ID

   You need your authenticated user’s ID to retrieve your block list. You can get it from the /2/users/me endpoint or use the ID from your tokens.

2. Request your block list

   cURL

   shellscript

   curl "https://api.x.com/2/users/123456789/blocking?\
   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 blocked users with pagination
   for page in client.users.get_blocking(
       "123456789",
       user_fields=["username", "verified", "created_at"],
       max_results=100
   ):
       for user in page.data:
           print(f"{user.username} - Created: {user.created_at}")
   

   import { Client } from "@xdevplatform/xdk";
   
   const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });
   
   // Get blocked users with pagination
   const paginator = client.users.getBlocking("123456789", {
     userFields: ["username", "verified", "created_at"],
     maxResults: 100,
   });
   
   for await (const page of paginator) {
     page.data?.forEach((user) => {
       console.log(`${user.username} - Created: ${user.created_at}`);
     });
   }
   
3. Review the response

   {
     "data": [
       {
         "id": "17874544",
         "name": "Example User",
         "username": "example_user",
         "verified": false,
         "created_at": "2008-12-04T18:51:57.000Z"
       }
     ],
     "meta": {
       "result_count": 1,
       "next_token": "abc123"
     }
   }
   

---

Block a user (Enterprise only)

1. Identify the target user

   Get the user ID of the account you want to block.

2. Send a block request

   cURL

   shellscript

   curl -X POST "https://api.x.com/2/users/123456789/blocking" \
     -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"target_user_id": "9876543210"}'
   

   from xdk import Client
   from xdk.oauth1_auth import OAuth1
   
   oauth1 = OAuth1(
       api_key="YOUR_API_KEY",
       api_secret="YOUR_API_SECRET",
       access_token="YOUR_ACCESS_TOKEN",
       access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
   )
   
   client = Client(auth=oauth1)
   
   # Block a user
   response = client.users.block(
       source_user_id="123456789",
       target_user_id="9876543210"
   )
   print(f"Blocking: {response.data.blocking}")
   

   import { Client, OAuth1 } from "@xdevplatform/xdk";
   
   const oauth1 = new OAuth1({
     apiKey: "YOUR_API_KEY",
     apiSecret: "YOUR_API_SECRET",
     accessToken: "YOUR_ACCESS_TOKEN",
     accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET",
   });
   
   const client = new Client({ oauth1 });
   
   // Block a user
   const response = await client.users.block("123456789", {
     targetUserId: "9876543210",
   });
   console.log(`Blocking: ${response.data?.blocking}`);
   
3. Confirm the block

   {
     "data": {
       "blocking": true
     }
   }
   

---

Unblock a user (Enterprise only)

1. Send an unblock request

   cURL

   shellscript

   curl -X DELETE "https://api.x.com/2/users/123456789/blocking/9876543210" \
     -H "Authorization: Bearer $USER_ACCESS_TOKEN"
   

   from xdk import Client
   from xdk.oauth1_auth import OAuth1
   
   oauth1 = OAuth1(
       api_key="YOUR_API_KEY",
       api_secret="YOUR_API_SECRET",
       access_token="YOUR_ACCESS_TOKEN",
       access_token_secret="YOUR_ACCESS_TOKEN_SECRET"
   )
   
   client = Client(auth=oauth1)
   
   # Unblock a user
   response = client.users.unblock(
       source_user_id="123456789",
       target_user_id="9876543210"
   )
   print(f"Blocking: {response.data.blocking}")
   

   import { Client, OAuth1 } from "@xdevplatform/xdk";
   
   const oauth1 = new OAuth1({
     apiKey: "YOUR_API_KEY",
     apiSecret: "YOUR_API_SECRET",
     accessToken: "YOUR_ACCESS_TOKEN",
     accessTokenSecret: "YOUR_ACCESS_TOKEN_SECRET",
   });
   
   const client = new Client({ oauth1 });
   
   // Unblock a user
   const response = await client.users.unblock("123456789", "9876543210");
   console.log(`Blocking: ${response.data?.blocking}`);
   
2. Confirm the unblock

   {
     "data": {
       "blocking": false
     }
   }
   

---

Next steps

Mutes

Mute users instead of blocking

Follows

Manage follows

Integration guide

Key concepts and best practices

API Reference

Full endpoint documentation