Integration Guide

Key concepts and best practices for integrating blocks endpoints

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

---

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
GET	/2/users/:id/blocking	Get list of blocked accounts
POST	/2/users/:id/blocking	Block an account
DELETE	/2/users/:source_user_id/blocking/:target_user_id	Unblock 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

---

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

shellscript

# 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"

---

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 blocks request

Mutes

Mute users instead of blocking

API Reference

Full endpoint documentation

Sample code

Working code examples