Skip to main content
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:
MethodDescription
OAuth 2.0 Authorization Code with PKCERecommended for new applications
OAuth 1.0a User ContextLegacy support
App-Only authentication is not supported. You must authenticate on behalf of a user.

​
Required scopes (OAuth 2.0)

ScopeRequired for
block.readRetrieving blocked accounts
block.writeBlocking and unblocking accounts
users.readRequired with block scopes

​
Endpoints overview

MethodEndpointDescriptionAvailability
GET/2/users/:id/blockingGet list of blocked accounts
Pay-per-useEnterprise
POST/2/users/:id/blockingBlock an accountEnterprise
DELETE/2/users/:source_user_id/blocking/:target_user_idUnblock an accountEnterprise

​
Fields and expansions

​
Default response

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

​
Available fields

FieldDescription
created_atAccount creation date
descriptionUser bio
profile_image_urlAvatar URL
public_metricsFollower/following counts
verifiedVerification status
ExpansionDescription
pinned_tweet_idUser’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"

​
Error handling

StatusErrorSolution
400Invalid requestCheck user ID format
401UnauthorizedVerify access token
403ForbiddenCheck scopes and permissions. Block/unblock require Enterprise
404Not FoundUser doesn’t exist
429Too Many RequestsWait 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