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

# Block a user by user ID, X (Twitter) API docs

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

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

`POST https://xquik.com/api/v1/x/users/{id}/block`

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

A write that must sign in to your X account first adds 10 credits. Xquik refunds them if the sign-in fails. A sign-in that works keeps them, even if X then refuses the write. See [the X sign-in fee](https://docs.xquik.com/guides/billing.md#x-sign-in-fee).

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={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
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

| Header | Type | Required | Description |
| - | - | - | - |
| `x-api-key` | `string` | No | Send your Xquik API key in this header. Alternatively, send an OAuth 2.1 bearer token. |
| `Authorization` | `string` | No | Send `Bearer <token>` instead of `x-api-key` when using OAuth 2.1. |
| `Idempotency-Key` | `string` | Yes | Unique key for this intended write. Reuse it only for an exact network replay. |
| `Content-Type` | `string` | Yes | Must be `application/json`. |

## Path parameters

| Path parameter | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | 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

| Body parameter | Type | Required | Description |
| - | - | - | - |
| `account` | `string` | Yes | X (Twitter) 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.

## Response examples

### 200 example

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
{
  "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
}
```

### 202 example

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/bash.json","/languages/csharp.json","/languages/go.json","/languages/java.json","/languages/javascript.json","/languages/kotlin.json","/languages/php.json","/languages/python.json","/languages/ruby.json","/languages/typescript.json"]}}
{
  "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
}
```

* **400** `{ "error": "missing_idempotency_key", "message": "Idempotency-Key is required. Generate one unique key for this write.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true }`
* **401** `{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }`
* **402** `{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }`
* **403** `{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }`
* **404** `{ "error": "account_not_found", "message": "X account not found. Connect it first at /dashboard/x-accounts." }`
* **409** `{ "error": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true }`
* **422** `{ "error": "x_rejected", "message": "X rejected this request. Check what you sent & the account on x.com before you try again." }`
* **429** `{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }`
* **500** `{ "error": "x_write_failed", "message": "Write action failed unexpectedly. Contact support if this persists." }`
* **503** `{ "error": "write_tracking_unavailable", "message": "Write tracking unavailable. Try again.", "charged": false, "chargedCredits": "0", "retryable": true, "safeToRetry": true }`


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