> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitter block API to block an X user by user ID

> Block 1 X user by ID from a connected X account. Store the write action, terminal result and billed credits. Retry only when safeToRetry is true. 10 credits.

> [tab] 200
>
> ```json theme={null}
> {
>   "object": "x_write_action",
>   "id": "12345",
>   "writeActionId": "12345",
>   "action": "block",
>   "status": "success",
>   "terminal": true,
>   "retryable": false,
>   "safeToRetry": false,
>   "statusUrl": "/api/v1/x/write-actions/12345",
>   "pollAfterMs": null
> }
> ```

> [tab] 202
>
> ```json theme={null}
> {
>   "object": "x_write_action",
>   "id": "12346",
>   "writeActionId": "12346",
>   "action": "block",
>   "status": "dispatching",
>   "terminal": false,
>   "retryable": false,
>   "safeToRetry": false,
>   "statusUrl": "/api/v1/x/write-actions/12346",
>   "pollAfterMs": 2000
> }
> ```

> [tab] 400
>
> ```json theme={null}
> {
>   "error": "missing_idempotency_key",
>   "message": "Idempotency-Key is required. Generate one unique key for this write.",
>   "charged": false,
>   "chargedCredits": "0",
>   "retryable": false,
>   "safeToRetry": true
> }
> ```

> [tab] 401
>
> ```json theme={null}
> {
>   "error": "unauthenticated",
>   "message": "Authentication required. Provide a valid API key or bearer token."
> }
> ```

> [tab] 402
>
> ```json theme={null}
> {
>   "error": "insufficient_credits",
>   "message": "Insufficient credits. Top up or subscribe to continue."
> }
> ```

> [tab] 403
>
> ```json theme={null}
> {
>   "error": "api_key_paused",
>   "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again."
> }
> ```

> [tab] 404
>
> ```json theme={null}
> {
>   "error": "account_not_found",
>   "message": "X account not found. Connect it first at /dashboard/x-accounts."
> }
> ```

> [tab] 409
>
> ```json theme={null}
> {
>   "error": "idempotency_conflict",
>   "message": "Idempotency-Key was already used with a different request.",
>   "charged": false,
>   "chargedCredits": "0",
>   "retryable": false,
>   "safeToRetry": true
> }
> ```

> [tab] 422
>
> ```json theme={null}
> {
>   "error": "x_rejected",
>   "message": "X rejected this request. Check what you sent & the account on x.com before you try again."
> }
> ```

> [tab] 429
>
> ```json theme={null}
> {
>   "error": "rate_limit_exceeded",
>   "message": "Too many requests. Try again later.",
>   "retryAfter": 60
> }
> ```

> [tab] 500
>
> ```json theme={null}
> {
>   "error": "x_write_failed",
>   "message": "Write action failed unexpectedly. Contact support if this persists."
> }
> ```

> [tab] 503
>
> ```json theme={null}
> {
>   "error": "write_tracking_unavailable",
>   "message": "Write tracking unavailable. Try again.",
>   "charged": false,
>   "chargedCredits": "0",
>   "retryable": true,
>   "safeToRetry": true
> }
> ```

> For the complete documentation index, see [llms.txt](https://docs.xquik.com/llms.txt).

**10 credits per call** · [All plans](https://xquik.com) from \$0.00012/credit

Each request blocks 1 user by ID.
Each request uses 1 connected X account.
X removes follows both ways when the block lands.
Unblocking never restores those follows.

```bash cURL theme={null}
curl -X POST https://xquik.com/api/v1/x/users/44196397/block \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Idempotency-Key: block-44196397" \
  -H "Content-Type: application/json" \
  -d '{"account":"myxaccount"}' | jq
```

```javascript Node.js theme={null}
const response = await fetch("https://xquik.com/api/v1/x/users/44196397/block", {
  method: "POST",
  headers: {
    "x-api-key": "xq_YOUR_KEY_HERE",
    "Idempotency-Key": "block-44196397",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ account: "myxaccount" }),
});
const result = await response.json();
if (!response.ok) {
  throw new Error(JSON.stringify(result));
}
process.stdout.write(
  `${JSON.stringify({ id: result.id, status: result.status, terminal: result.terminal })}\n`,
);
```

```python Python theme={null}
import requests

response = requests.post(
    "https://xquik.com/api/v1/x/users/44196397/block",
    headers={
        "x-api-key": "xq_YOUR_KEY_HERE",
        "Idempotency-Key": "block-44196397",
    },
    json={"account": "myxaccount"},
)
response.raise_for_status()
result = response.json()
print(result["id"], result["status"], result["terminal"])
```

## Block one user by ID

Put the exact user ID in the request path.
Put the connected account username or ID in the body.
That account blocks the user.

The blocked user can't follow that account or see its posts while signed in.
X tells the blocked user only when they open the account's profile.

## Choose block or mute

| Intent | API route | Result |
| - | - | - |
| Stop a user from following or replying | `POST /x/users/{id}/block` | Blocks the user and removes follows both ways. |
| Hide a user's posts without telling them | `POST /x/users/{id}/mute` | Mutes the user. Follows stay. |
| Undo a block | `DELETE /x/users/{id}/block` | Unblocks the user. Follows stay removed. |

Use [Unblock user](https://docs.xquik.com/api-reference/x-write/unblock.md) to reverse a block.

## Save a receipt

Save the action first. Then update your local record.

| Column | Source | Rule |
| - | - | - |
| `acting_account` | Request `account` | Keep the connected X account with the action. |
| `user_id` | Path `id` | Keep the exact user ID. |
| `idempotency_key` | Request header | Generate 1 key for this account and user ID. |
| `write_action_id` | Response `id` | Store the action before polling. |
| `terminal` | Response `terminal` | Change the local record only when `true`. |
| `safe_to_retry` | Response `safeToRetry` | Retry only when this value is `true`. |

## Handle errors

Never infer failure from a client timeout.
Poll a returned action before sending another request.

* For `400`, correct the user ID or account value.
* For `401`, replace invalid Xquik authentication.
* For `402`, add credits before another request.
* For `403`, reconnect the selected X account.
* For `409`, keep the original action and payload.
* For `422`, review the X rejection before retrying.
* For `429`, wait for `Retry-After`.
* For `500` or `503`, follow `safeToRetry` and `terminal`.

## Headers

**x-api-key** `string`

Send your Xquik API key in this header. Alternatively, send an OAuth 2.1 bearer token.

**Authorization** `string`

Send `Bearer <token>` instead of `x-api-key` when using OAuth 2.1.

**Idempotency-Key** `string` *required*

Unique key for this intended write. Reuse it only for an exact network replay.

**Content-Type** `string` *required*

Must be `application/json`.

## Path parameters

**id** `string` *required*

User to block. Send a user ID or a username with or without `@`. A URL-encoded profile URL such as `x.com/nasa` also works.
An unknown username returns `422 x_target_not_found`. See [path IDs](https://docs.xquik.com/api-reference/overview.md#path-ids).

## Body

**account** `string` *required*

X username or account ID identifying which connected X account acts. Xquik strips the `@` prefix if included.

## Response

## Durable write recovery

> [!WARNING]
>
> Send one unique `Idempotency-Key` per intended write.
> Replay the same account, target, payload, and media after a lost response.
> Keep the original key for that replay.

1. Store `id`, the nested `hash` in `request`, `billing`, and `statusUrl`.
2. Poll after `Retry-After` or `pollAfterMs` when `terminal` is `false`.
3. Retry only when `safeToRetry` is `true`.
4. Use a new key when `nextAction.requiresNewIdempotencyKey` is `true`.

### 200 terminal or 202 active

* After HTTP `200`, store the result and settled billing.
* After HTTP `202`, poll the same action. Never submit another write.
* After HTTP `400`, fix the named field. Use a new idempotency key.
* After HTTP `401`, fix authentication. Do not retry unchanged.
* After HTTP `402`, fund the account before another write.
* After HTTP `403`, reconnect the account.
* After HTTP `409`, keep the original action. Use a new key for new input.
* After HTTP `422`, fix the rejected request before retrying.
* After HTTP `429`, wait for `Retry-After`. Follow `nextAction`.

See [Get Write Action Status](https://docs.xquik.com/api-reference/x-write/get-write-action-status.md)
for every lifecycle field and terminal state. That page also lists every billing
field and retry rule.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.