Integration Guide

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

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

Authentication

Blocks endpoints require user authentication:

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
`block.read`	Retrieving blocked accounts
`block.write`	Blocking and unblocking accounts
`users.read`	Required with block scopes

Endpoints overview

Method	Endpoint	Description	Availability
GET	`/2/users/:id/blocking`	Get list of blocked accounts	Pay-per-useEnterprise
POST	`/2/users/:id/blocking`	Block an account	Enterprise
DELETE	`/2/users/:source_user_id/blocking/:target_user_id`	Unblock an account	Enterprise

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

What happens when you block

They can't

See your Posts (unless logged out)
Follow you
Send you DMs
Add you to Lists
Tag you in photos

You can't

See their Posts
Follow them
Send them DMs

When you block someone who follows you, they are automatically unfollowed.

Pagination

For users with large block lists, results are paginated:

cURL

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

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

from xdk import Client

# Use OAuth 2.0 user access token
client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# The SDK handles pagination automatically
all_blocked = []

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

print(f"Blocked {len(all_blocked)} users")

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

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

async function getAllBlockedUsers(userId) {
  const allBlocked = [];

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

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

  return allBlocked;
}

// Usage
const blocked = await getAllBlockedUsers("123");
console.log(`Blocked ${blocked.length} users`);

Error handling

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

Next steps

Quickstart

Make your first blocks request

Mutes

Mute users instead of blocking

API Reference

Full endpoint documentation

Sample code

Working code examples

​Authentication

​Required scopes (OAuth 2.0)

​Endpoints overview

​Fields and expansions

​Default response

​Available fields

​What happens when you block

They can't

You can't

​Pagination

​Error handling

​Next steps

Quickstart

Mutes

API Reference

Sample code

Authentication

Required scopes (OAuth 2.0)

Endpoints overview

Fields and expansions

Default response

Available fields

What happens when you block

Pagination

Error handling

Next steps