Blocked Accounts API

Blocked Accounts returns the accounts blocked by the account behind your session, as cursor-paginated full user objects. It reads your own list only: X provides no way to read another account's block list, which is why there is no user_id parameter. Each page is one $0.0008 read.

curl -X GET "https://example.com/user/blocking?count=20&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"

{  "count": 1,  "next_cursor": "1353384573435056128|2071116068906074107",  "users": [    {      "id": "1353384573435056128",      "username": "cryptorover",      "name": "Crypto Rover",      "verified": true,      "followers_count": 812443,      "description": "Daily crypto analysis.",      "created_at": "Sun Jan 24 16:50:08 +0000 2021",      "profile_image_url": "https://pbs.twimg.com/profile_images/1891433835675475969/J-TloTb6_normal.png"    }  ]}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue.",  "top_up_url": "https://www.twitterapis.com/dashboard/buy-credits?utm_source=api&utm_medium=402"}

{  "error": "forbidden",  "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Use this endpoint to audit or sync the blocked-accounts list tied to your own registered session, for example to mirror your block list into an external moderation tool. Unlike other User Reads endpoints that accept a user_id to look up any public account, this one always returns your own account's data since X does not expose another account's block list.

Notes

• Needs a session for the account you are reading: either register one once (POST /customer/session), or pass per-call inline credentials as x-auth-token and x-ct0 request headers, which let a single API key act as many accounts. Returns 409 session_required if neither is supplied, 401 session_dead when the session has expired.
• An empty users array is a real answer: it means the account blocks nobody. It is never a silent parse failure. If the endpoint cannot read the list it returns an error status, not an empty page, so you can trust a 200 with zero users.
• Like the other paginated user lists, next_cursor can stay non-null on the final page; stop when the users array is empty.

Pagination

This endpoint is cursor-paginated and returns roughly 20 records per call. Pass the next_cursor from each response back as the cursor parameter to read the next page. Stop when the records array comes back empty: follower-graph endpoints return a non-null cursor even on the final page, so the empty array is the only reliable stop signal. See Pagination for the full loop.

Related endpoints

• User Info by Username: Fetch a full profile by @handle.
• User Info by ID: Fetch a full profile by numeric user ID.

FAQ

Can I check whether a specific account has blocked me, or list someone else's block list?

No. This endpoint only returns the block list of the account behind your registered session, because X exposes no API surface for reading another account's blocks. There is deliberately no user_id parameter on this endpoint; if you need relationship data between two specific accounts, use the follow-relationship endpoint instead.

How do I page through a large block list?

Set count (default 20, max 100) to control page size, then pass the next_cursor value from the previous response as the cursor parameter on your next call. Keep paging while has_more is true; each call costs $0.0008 regardless of how many results the page contains.