---
title: "Submit a scrape request (auto or manual proxy mode; async, or wait for the result directly)"
method: POST
path: "/v1/scrape"
tags: ["scrape"]
---

# Submit a scrape request (auto or manual proxy mode; async, or wait for the result directly)

`POST /v1/scrape`

## Request

- Base URL: `https://barchin.net/api`
- URL: `https://barchin.net/api/v1/scrape`
- Auth: HTTP bearer

## Query parameters

- `wait` integer: 0 (default) = async, returns request_id. N > 0 = wait up to N seconds for the result. ۰ (پیش‌فرض) = async و برگرداندن request_id. عدد > ۰ = تا این تعداد ثانیه منتظر نتیجه بمان و همان را مستقیم برگردان (سقف سرور: SYNC_MAX_WAIT_SECONDS)؛ اگر در این مدت آماده نشد، ۲۰۲ با request_id برمی‌گردد — درخواست **ادامه دارد** و شکست نخورده است. برای اجراهای طولانی (مثلاً آنبلاکر) async بفرستید و status_url را poll کنید.
- `format` 'html' | 'markdown' | 'text': Result format. markdown/text are derived from the stored HTML at read time at no extra cost.
- `max_chars` integer, nullable: Truncate markdown/text to this many characters; sets truncated=true.

## Request body

- ScrapeCreateIn
  - `url` string, required
  - `js_enabled` boolean: Render the full page with a browser. **Default: on.** Send false for pages that don't need JavaScript to pay 5 fewer credits.
  - `mode` 'auto' | 'manual'
  - `proxy` 'datacenter' | 'residential' | 'unblocker': The public name of a tier; this is what the API accepts and returns.
  - `country` string, nullable: Two-letter country code the exit IP should be from (e.g. ir, de, us). Default: worldwide. Sites that only serve their own country's users reject foreign IPs, and rotating proxies does not help there since the next IP is foreign too. Has no effect on the datacenter pool (a single fixed IP, wherever it was bought).
  - `wait_for` string, nullable: CSS selector. Only with js_enabled=true: after the page loads, wait for this element to appear in the DOM (up to 20s) before reading the HTML. For pages that fetch price/content in a separate request after the initial render. The request does not fail if the element never appears — the HTML at that point is returned as-is.
  - `wait_ms` integer: Milliseconds (up to 15000). Only with js_enabled=true: wait this long after the page loads (and after wait_for, if given) before reading the HTML. `delay` is also accepted as this field's name.
  - `fresh` boolean: true = ignore any cached response for this URL and fetch the page again. A request with wait_for or wait_ms is always fetched fresh. `no_cache` is also accepted.
  - `accept_binary` boolean: Accept a non-HTML body — a PDF, an image, an archive — instead of failing with `unsupported_content_type`. The file is fetched over plain HTTP through the same proxy ladder (a 403/429 escalates to a residential IP exactly as a page would), kept for the usual result retention and returned in `result` as `content_base64` (up to 15 MB) plus a bearer-protected `download_url`; `html`/`markdown`/`text` are null and `size_bytes` is the file size. Whatever the server sends is stored as-is, an HTML body included. Requires js_enabled=false — a file is never rendered, so the render surcharge never applies. پذیرش پاسخ غیر-HTML (PDF، تصویر، آرشیو…): فایل از همان نردبان پروکسی گرفته می‌شود و در `result` به‌صورت `content_base64` (تا 15 مگابایت) و `download_url` برمی‌گردد. فقط با js_enabled=false.

## Response `200`

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

- ScrapeRequestDetailOut
  - `request_id` string, uuid, required
  - `url` string, required
  - `js_enabled` boolean, required
  - `wait_for` string, nullable
  - `wait_ms` integer
  - `fresh` boolean
  - `accept_binary` boolean
  - `mode` 'auto' | 'manual', required
  - `country` string, nullable
  - `proxy_requested` 'datacenter' | 'residential' | 'unblocker', required: The public name of a tier; this is what the API accepts and returns.
  - `proxy_used` 'datacenter' | 'residential' | 'unblocker', required: The public name of a tier; this is what the API accepts and returns.
  - `status` 'queued' | 'processing' | 'done' | 'failed', required
  - `credits_held` integer, required
  - `credits_charged` integer, nullable, required
  - `credits_released` integer, required
  - `source` 'api' | 'dashboard', required
  - `api_key_id` string, uuid, nullable, required
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable, required
  - `queued_ms` integer, nullable
  - `duration_ms` integer, nullable
  - `total_ms` integer, nullable
  - `error` ScrapeErrorOut
    - `code` string, required
    - `message` string, required
  - `warning` ScrapeWarningOut: Advisory only — the request was accepted and runs exactly as asked.
    - `code` string, required
    - `message` string, required
  - `refund` RefundOut
    - `credits` integer, required
    - `message` string, required
  - `result` ScrapeResultOut
    - `html` string, nullable: در صورت include_html=false یا format=markdown/text برگردانده نمی‌شود.
    - `final_url` string, nullable, required
    - `http_status` integer, nullable, required
    - `size_bytes` integer, required
    - `fetched_at` string, date-time, required
    - `expires_at` string, date-time, required
    - `markdown` string, nullable: Markdown derived from the stored HTML at read time (format=markdown). Null otherwise.
    - `text` string, nullable: Plain text derived from the stored HTML at read time (format=text). Null otherwise.
    - `truncated` boolean: True when max_chars cut the markdown/text content short.
    - `content_type` string, nullable: accept_binary only: the media type the server sent (e.g. application/pdf), as stored. Null for page requests.
    - `download_url` string, nullable: accept_binary only: absolute URL that streams the file back with its content type. Needs the same Authorization header as this endpoint; valid until expires_at.
    - `content_base64` string, nullable: accept_binary only: the file itself, base64-encoded (up to 15 MB). Omitted with include_html=false — use download_url instead.
  - `result_expired` boolean

## Other responses

- `202`: در صف (حالت async، یا wait که به نتیجه نرسید)
- `400`: ترکیب نامعتبر mode و proxy
- `401`: Unauthorized
- `402`: Payment Required
- `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)