---
title: "Run several inputs of one actor in one call — each an ordinary run with its own id and bill (async, or wait for all)"
method: POST
path: "/v1/actors/{slug}/batch"
tags: ["actors"]
---

# Run several inputs of one actor in one call — each an ordinary run with its own id and bill (async, or wait for all)

`POST /v1/actors/{slug}/batch`

## Request

- Base URL: `https://barchin.net/api`
- URL: `https://barchin.net/api/v1/actors/{slug}/batch`
- Auth: HTTP bearer

Submit several inputs of one actor at once and get the runs back keyed by your own
labels. Built for callers that ask the same actor a handful of related questions per
unit of work — a datasheet lookup that fires three to five `google-search` queries per
product — and want one round trip instead of five.

**Nothing about a run changes.** Every item becomes an ordinary run: its own `run_id`,
its own hold, its own bill, its own place in the queue, visible under
`GET /v1/actors/{slug}/runs` like any other. The batch is a convenience over the
submission and, with `wait`, over the waiting.

**All-or-nothing up front.** Every item is validated by the actor before any of them
is submitted; one bad item fails the whole batch with 422 (`details.key` names it)
and nothing is reserved. The sum of the holds is checked against your balance the same
way — 402 `insufficient_credits` with `details.required`/`details.balance`, nothing
submitted — so a batch you cannot afford never starts half-way. Items are then
submitted in order. Should one still fail after earlier ones were accepted (a credit
race with another request of yours, a queue outage), the earlier runs are already
executing and are returned as usual; that item lands under `errors` with nothing
reserved for it, and is the only thing to resubmit.

**Waiting.** With `wait` (query or body), the call blocks until *every* submitted run
has finished or the budget runs out: 200 when all finished (`finished == submitted`,
`pending` empty, each result carrying its dataset), else 202 with `Retry-After` and the
unfinished keys in `pending`. A 202 is not a failure — those runs keep going; poll them
by `run_id`, do not resubmit, a resubmit is a second charge. Without `wait` the answer
is an immediate 202 with every key pending.

`mode`, `proxy` and `country` apply to every item alike; split the batch if the items
need different ones.

چند ورودی از یک اکتور را یک‌جا بفرستید و اجراها را با برچسب‌های خودتان تحویل بگیرید.
هیچ‌چیز اجرا عوض نمی‌شود: هر مورد یک اجرای عادی است با `run_id`، رزرو و صورت‌حساب خودش.
همه‌ی موارد پیش از ارسال اعتبارسنجی می‌شوند و مجموع رزرو با موجودی سنجیده می‌شود؛ یک مورد
نامعتبر یا موجودی ناکافی کل دسته را بدون رزرو هیچ کردیتی رد می‌کند. با `wait` تا تمام شدن
همه‌ی اجراها منتظر می‌مانیم: ۲۰۰ اگر همه تمام شدند، وگرنه ۲۰۲ با کلیدهای تمام‌نشده در
`pending` — آن اجراها ادامه دارند؛ با `run_id` دنبالشان کنید و دوباره نفرستید.

## Path parameters

- `slug` string, required

## Query parameters

- `wait` integer: 0 = async, every key comes back pending. >0 = wait up to this many seconds for ALL the runs to finish (server ceiling: SYNC_MAX_WAIT_SECONDS); 200 when they all did, else 202 with the unfinished keys in `pending` — those runs **continue**; poll them. Also accepted in the body as `wait`; the query parameter wins when both are given. ۰ = async، همه‌ی کلیدها در pending برمی‌گردند؛ >۰ = تا این ثانیه منتظر تمام شدن **همه‌ی** اجراها بمان (سقف سرور: SYNC_MAX_WAIT_SECONDS). اگر همه تمام شدند ۲۰۰، وگرنه ۲۰۲ با کلیدهای تمام‌نشده در pending — آن اجراها **ادامه دارند**؛ دنبالشان کنید. در بدنه هم به‌صورت `wait` پذیرفته می‌شود؛ اگر هر دو باشند پارامتر کوئری برنده است.
- `mode` 'auto' | 'manual'
- `proxy` 'datacenter' | 'residential' | 'unblocker': The public name of a tier; this is what the API accepts and returns.
- `country` string, nullable: Applied to every item. Two-letter country code the exit IP should be from (e.g. ir). Default: worldwide. An actor with a fixed exit country ignores it (with a warning on each run). برای همه‌ی موارد اعمال می‌شود. کد دو حرفی کشوری که IP خروجی باید از آن باشد (مثل ir). پیش‌فرض: جهانی. اکتوری که کشور خروجی ثابت دارد آن را نادیده می‌گیرد (با warning روی هر اجرا).

## Request body

- ActorBatchIn: A batch of inputs for one actor. Validated as a whole before anything is held.
  - `queries` ActorBatchItemIn[], required: 1–20 items, each an ordinary input of this actor plus a `key`. Every item is validated before any of them is submitted: one bad item fails the whole batch with 422 and nothing is reserved. `inputs` is accepted as an alias for actors whose input is not a search query. ۱ تا ۲۰ مورد؛ هر کدام ورودی عادی همین اکتور به‌علاوه‌ی `key`. همه‌ی موارد قبل از ارسال هر کدام اعتبارسنجی می‌شوند: یک مورد نامعتبر کل دسته را با ۴۲۲ رد می‌کند و هیچ کردیتی رزرو نمی‌شود. برای اکتورهایی که ورودی‌شان عبارت جست‌وجو نیست، می‌توانید به جای `queries` از `inputs` استفاده کنید.
    - `url` string, nullable
    - `key` string, required: Your own label for this item (1–64 characters), unique within the batch. `results`, `pending` and `errors` in the response are keyed by it, so use whatever lets you match a run back to the question you asked. برچسب خودتان برای این مورد (۱ تا ۶۴ کاراکتر)، یکتا در همین دسته. `results`، `pending` و `errors` در پاسخ با همین کلید برمی‌گردند؛ هر چیزی که کمک کند هر اجرا را به پرسش خودتان وصل کنید.
  - `wait` integer: Same as the `?wait=` query parameter, for callers that prefer it in the body: 0 = return at once with every key pending; >0 = wait up to this many seconds for all the runs to finish (server ceiling: SYNC_MAX_WAIT_SECONDS). The query parameter wins when both are given. معادل پارامتر `?wait=`، برای کسانی که ترجیح می‌دهند در بدنه بفرستند: ۰ = بلافاصله با همه‌ی کلیدها در `pending` برگرد؛ >۰ = تا این ثانیه منتظر تمام شدن همه‌ی اجراها بمان (سقف سرور: SYNC_MAX_WAIT_SECONDS). اگر هر دو فرستاده شوند، پارامتر کوئری برنده است.

## Response `200`

همه‌ی اجراها تمام شدند (حالت wait)

- ActorBatchOut: The runs a batch produced, keyed by the caller's labels. 200 when `wait` was given and every submitted run finished inside it; 202 otherwise — the runs under `pending` are still executing and are polled like any other run (`GET /v1/actors/{slug}/runs/{run_id}`, or `/v1/actor-runs/{run_id}`).
  - `actor_slug` string, required
  - `submitted` integer, required: How many items became runs (each with its own id, hold and bill). Items under `errors` are not counted. چند مورد به اجرا تبدیل شد (هر کدام با شناسه، رزرو و صورت‌حساب خودش). موارد داخل `errors` شمرده نمی‌شوند.
  - `finished` integer, required: How many of the submitted runs had reached a final status (succeeded or failed) when this response was written. چند اجرا از اجراهای ارسال‌شده هنگام نوشتن این پاسخ به وضعیت نهایی (succeeded یا failed) رسیده بودند.
  - `pending` string[], required: Keys of the runs still queued or processing, in the order they were submitted. They keep running after this response: poll them, do not resubmit — a resubmit is a second charge. کلید اجراهایی که هنوز در صف یا در حال پردازش‌اند، به ترتیب ارسال. این اجراها بعد از این پاسخ هم ادامه دارند: آن‌ها را دنبال کنید و دوباره نفرستید — ارسال دوباره یعنی یک هزینه‌ی دوم.
  - `results` object, required: Every submitted run, by key — the same object `GET /v1/actors/{slug}/runs/{run_id}` returns, so a finished one carries its `dataset` and a queued one its `queue_position`/`eta_ms`. همه‌ی اجراهای ارسال‌شده، با کلید — همان شیئی که `GET /v1/actors/{slug}/runs/{run_id}` برمی‌گرداند؛ اجرای تمام‌شده `dataset` دارد و اجرای در صف `queue_position`/`eta_ms`.
  - `errors` object, required: Items that were accepted by validation but could not be submitted after earlier ones already had been (a credit race, a queue outage), by key. Nothing was reserved for them; resubmit just these. Empty on a clean batch. مواردی که اعتبارسنجی را گذراندند ولی بعد از ارسال موارد قبلی نتوانستند ارسال شوند (رقابت روی موجودی، قطعی صف)، با کلید. برای این‌ها چیزی رزرو نشده؛ فقط همین‌ها را دوباره بفرستید. در یک دسته‌ی سالم خالی است.
  - `credit_balance` integer, required: Your balance when this response was written: after every run's hold, and after the release of any run that had already finished. موجودی شما هنگام نوشتن این پاسخ: پس از رزرو همه‌ی اجراها و آزاد شدن رزرو اجراهایی که تا آن لحظه تمام شده بودند.

## Other responses

- `202`: پذیرفته شد؛ کلیدهای `pending` هنوز در حال اجرا هستند (async، یا wait که به پایان همه نرسید)
- `400`: ترکیب نامعتبر mode و proxy
- `401`: Unauthorized
- `402`: موجودی برای رزرو مجموع دسته کافی نیست؛ هیچ موردی ارسال نشد
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `503`: Service Unavailable

---

[API](https://skmtc.dev/barchin/apis/barchin-scraping-api.md) · [All operations](https://skmtc.dev/barchin/apis/barchin-scraping-api/llms.txt) · [OpenAPI document](https://skmtc.dev/barchin/apis/barchin-scraping-api/revisions/fe97e4690cc3?raw)