SocialMate Local API

Anti-ban status

Read live risk, warming, night-mode, pause state, and the per-minute/hour/day rate limits.

Every send is governed by SocialMate's anti-ban pipeline. This endpoint lets you read the exact live state — risk, warming, rate budgets, and pause status — so you can decide whether to send now, pace yourself, or back off before you ever hit a block.

GET /v1/accounts/{id}/antiban

scope: readFree

{
  "data": {
    "accountId": "a1b2c3",
    "riskLevel": "safe",
    "riskScore": 23,
    "warmingDay": 1,
    "messagesToday": 41,
    "dailyLimit": 500,
    "paused": false,
    "pauseScope": null,
    "pauseReason": null,
    "autoResumeAt": null,
    "nightMode": false,
    "warming": {
      "currentDay": 1,
      "totalDays": 3,
      "ageHours": 30,
      "isComplete": false,
      "phase":     { "id": "warming_day1", "startHours": 24, "endHours": 48, "maxSends": 50, "label": "Day 1 — building trust" },
      "nextPhase": { "id": "warming_day2", "startHours": 48, "endHours": 72, "maxSends": 100, "label": "Day 2 — almost warm" },
      "todayLimit": 50,
      "todaySent": 41,
      "msUntilNextPhase": 64800000
    },
    "rateLimits": {
      "perMinute": { "current": 4, "max": 30 },
      "perHour":   { "current": 18, "max": 100 },
      "perDay":    { "current": 41, "max": 500 },
      "burst":     { "current": 1, "max": 5 }
    }
  }
}

This is a Pro account on its first warming day. Note that warming is null once the number is fully warm — the object only appears during the 72-hour ramp.

Fields

Field	Meaning
`riskLevel` / `riskScore`	The account's current risk band and numeric score (0–100). The band is one of `safe` (score < 40), `elevated` (40–59), `warning` (60–79), or `critical` (≥ 80).
`warmingDay`	Day index (0–3) in the 3-day warm-up ramp; new numbers send less.
`warming`	`null` once the number is fully warm, otherwise an object describing the ramp: `currentDay`/`totalDays`, the current `phase` and `nextPhase` ({`id`, `label`, `startHours`, `endHours`, `maxSends`}), `todayLimit`/`todaySent` (the active warming send budget), and `msUntilNextPhase`.
`messagesToday` / `dailyLimit`	Sent count over the rolling last 24 hours against the daily cap — identical to `rateLimits.perDay.current` / `max`. Despite the name, it never resets at midnight.
`paused`, `pauseScope`, `pauseReason`, `autoResumeAt`	Whether sending is paused (global or per-account), why, and when it auto-resumes.
`nightMode`	Whether quiet hours are suppressing sends right now.
`rateLimits`	Live `current`/`max` for the per-minute, per-hour, per-day, and burst windows. All windows are rolling — per-day means the last 24 hours, not the calendar day.

Rate caps by tier

The max values in rateLimits are your account's fixed tier ceilings — they do not shrink during warming. Instead, a new number is held to a separate, smaller per-phase send budget exposed as warming.todayLimit, which ramps 0 → full over the first 72 hours. So the freshly-linked Pro account above can hit its warming cap (todayLimit 50) long before the per-day ceiling (500).

Window	Free	Pro
Per minute	10	30
Per hour	30	100
Per day	200	500
Burst (10s window)	3	5

High-Volume Mode (Pro). Pro accounts can opt into a higher in-app rate override — up to 120/min · 1500/hr · 5000/day — after the number has warmed for at least 72 hours and the override is explicitly acknowledged. It is an in-app setting, not an API endpoint; toggling it emits the account.danger_mode_enabled / account.danger_mode_disabled webhooks (the wire event names keep the legacy danger_mode key). Pushing past the standard caps raises ban risk — use it deliberately.

Block reasons

When the pipeline blocks a send, the response is HTTP 429 with an error.reason field naming the specific block. Branch on reason — it is the stable value. The error.code depends on the route: the unified send (POST /messages) reports rate_limited, while the signal-lane and group routes (presence, reaction, mark-read, the legacy media endpoint, group ops) carry an explicit ANTI_BAN_<REASON> code — e.g. ANTI_BAN_SIGNAL_RATE_LIMIT. The full reason set:

reason	Why
`warming`	The account is too new for the requested volume.
`rate_limit`	A token-bucket / window cap was hit (see `rateLimits`).
`risk_critical`	Risk score reached the critical threshold; the account auto-cools and resumes on its own once the score recovers to a safe level (not a fixed wait).
`paused_global`	A global pause is active.
`paused_account`	This account is paused.
`night_mode`	Quiet hours are active.
`banned`	The account is banned — sends are never allowed.
`unknown_account`	The account id has no record.
`duplicate_text`	The identical-message ratio exceeded the safety cap.
`signal_rate_limit`	The signal lane cap was hit (typing / mark-read / reaction). Distinct from `rate_limit` so you can retry a signal without believing your message budget is exhausted — the two lanes are budgeted independently (Free 20/min, Pro 60/min).

Blocks also include retryAfterMs (when applicable). On Pro, a blocked send is auto-queued and replayed when the condition clears — see Sending messages.

Pattern. Poll /antiban before a burst, or simply send and let the pipeline pace you — on Pro the auto-queue handles back-pressure so you rarely need to check first.