The batch endpoint runs up to 20 texts through the Telm anti-spam engine in a single POST, returning a verdict for each. It is rules-only (no AI level) and available on the Pro plan and above. Quota is charged per item, so a batch of ten texts spends ten calls. For a single text with an optional AI check, use the regular spam-check endpoint.
1What batch spam check does
Batch spam check lets you score many texts at once instead of making one request per message. You send a POST to /spam/check-batch with an array of items and get back an array of verdicts in the same order — ideal for classifying a backlog of messages, moderating a comment feed, or evaluating detection quality over a sample.
The batch runs the same rules engine that protects live groups, but it does not run the AI level, which keeps each request fast and predictable. If you need the AI check, use the single spam-check endpoint with the AI option enabled, one text at a time.
- Endpoint: POST /api/public/v1/spam/check-batch.
- Scores up to 20 texts per request, verdicts returned in input order.
- Rules-only: the AI level is not run in batch mode.
2Request format
The request body is a JSON object with an items array. Each item has a required text field and an optional context object that mirrors what the live engine sees — the group_id, the sender user_telegram_id, whether the sender is a new user, the username, and flags such as allow_sales and crypto_community.
When an item includes a group_id in its context, the check applies that group's custom rules and settings, so your account must be an admin of that group or the whole request is rejected. Omit the group context to score against the global ruleset instead.
- Top-level field: items — an array of one to twenty entries.
- Each item: text (required) and an optional context object.
- Context can carry group_id, user_telegram_id, is_new_user, username, allow_sales, crypto_community.
- A group context requires that you administer that group.
3Response format
The response is a JSON object with a results array — one verdict per input item, in the same order — and a quota object showing your used count, daily limit, and reset time.
Each verdict tells you the classification and why. The verdict field is one of spam, suspicious or clean. Alongside it you get a numeric score and confidence, a recommended_action (one of none, review, warn, mute, kick, ban or delete), a list of categories, human-readable reasons, the names of the matched_rules, and a signals map with the individual scoring contributions.
- results — one verdict per item, in input order.
- verdict — spam, suspicious or clean.
- Each verdict also has score, confidence, recommended_action, categories, reasons, matched_rules and signals.
- quota — used, limit and reset_at, echoed in the body.
4Limits and quota cost
A batch is capped at 20 items per request, and each text is limited to 10,000 characters. The whole request body has a size ceiling as well, so very large payloads are rejected before processing. If you have more than 20 texts, split them across several requests.
Quota is charged per item, not per request: a batch of ten texts spends ten calls from your daily quota. This is the same budget described in API rate limits and quotas, and the response carries the usual X-Quota-Limit, X-Quota-Used and X-Quota-Reset headers.
- Up to 20 items per request; up to 10,000 characters per text.
- Quota cost equals the number of items in the batch.
- Standard X-Quota-* headers apply, plus a quota object in the body.
5Errors and timeouts
Bad requests return 400 with a specific code: an empty items array, a batch over the item limit, a missing text, or a text over the length limit. A group context you do not administer returns 404 for that item. A plan below Pro returns 403 with a plan_required code.
If processing a batch exceeds its time budget, the API returns 504 and refunds the quota for the items it did not finish, so you are only charged for work that completed. If you see timeouts, send smaller batches.
- 400 — empty_batch, batch_too_large, missing_text or text_too_long.
- 404 — a group in an item context is not one you administer.
- 403 plan_required — the batch endpoint needs Pro or higher.
- 504 timeout — the batch ran too long; unfinished items are refunded. Send fewer texts.