> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Zenrows HTTP API serves Fetch and Extract (extract=auto) at https://api.zenrows.com/v1/, Crawl at https://api.zenrows.com/v1/crawls, and Batch at https://async.api.zenrows.com/v1. Fetch, Extract, Crawl and Batch are described in OpenAPI 3.1 at https://www.zenrows.com/openapi.json and listed in the RFC 9727 API catalog at https://www.zenrows.com/.well-known/api-catalog. Every endpoint also has its own page under /api-reference with its schema. Use the spec for exact parameter names and types. Crawl's endpoints, parameters and errors are also at https://docs.zenrows.com/crawl/endpoints.md. To call Zenrows from an agent, connect the MCP server at https://mcp.zenrows.com/mcp. To search these docs from an agent, connect the docs MCP server at https://docs.zenrows.com/mcp. Agent skills for Zenrows are published at https://github.com/ZenRows/cli and install with `npx skills add ZenRows/cli`.

# Batch Setup

> Get started with Zenrows Batch: find your API key, authenticate, submit your first batch job, and retrieve the results.

This guide walks you through setting up Batch. You'll confirm your access, locate your API key, authenticate, submit your first batch job, and download the results end to end.

> [!NOTE]
>
> Batch is available to every Zenrows account. You just need an active Zenrows API key; your existing Fetch key works without any extra setup.

## Initial setup

Follow these steps to get ready:

**1. Sign in to Zenrows**

Visit the Registration page to create an account, or log in if you already have one. Batch uses the **same API key as Fetch**, which you'll find in your dashboard.

[Sign up free](https://app.zenrows.com/register)
[Log in](https://app.zenrows.com/login)

**2. Note the base URL**

All REST requests go to `https://async.api.zenrows.com/v1`.

## Authentication

Authenticate every request with your API key in the `X-API-Key` header. For security, the key travels in a header and never in the URL.

```bash theme={"theme":"css-variables"}
X-API-Key: YOUR_ZENROWS_API_KEY
```

Store the key in an environment variable so your code can read it instead of hard-coding it:

```bash theme={"theme":"css-variables"}
export ZENROWS_API_KEY="YOUR_ZENROWS_API_KEY"
```

## Submit your first job

This minimal example submits a **closed job** (one where you know all URLs up front) with JavaScript rendering enabled. Replace `YOUR_ZENROWS_API_KEY` with your key.

```python Python theme={"theme":"css-variables"}
## pip install requests
import requests, json

headers = {'X-API-Key': 'YOUR_ZENROWS_API_KEY', 'Content-Type': 'application/json'}
payload = {
    'type': 'regular',
    'status': 'closed',
    'zenrows_params': {'js_render': 'true'},
    'tasks': [
        {'url': 'https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie'},
        {'url': 'https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket'},
    ],
}
response = requests.post('https://async.api.zenrows.com/v1/jobs', headers=headers, data=json.dumps(payload))
job = response.json()
print('submitted', job['job_id'], job['latest_run']['status'])
```

```javascript Node.js theme={"theme":"css-variables"}
// npm install axios
const axios = require('axios');

axios({
    url: 'https://async.api.zenrows.com/v1/jobs',
    method: 'POST',
    headers: { 'X-API-Key': 'YOUR_ZENROWS_API_KEY' },
    data: {
        type: 'regular',
        status: 'closed',
        zenrows_params: { js_render: 'true' },
        tasks: [
            { url: 'https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie' },
            { url: 'https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket' },
        ],
    },
})
    .then(response => console.log('submitted', response.data.job_id, response.data.latest_run.status))
    .catch(error => console.log(error));
```

```java Java theme={"theme":"css-variables"}
import org.apache.hc.client5.http.fluent.Request;
import org.apache.hc.core5.http.ContentType;

public class FirstJob {
    public static void main(final String... args) throws Exception {
        String body = "{"
            + "\"type\":\"regular\",\"status\":\"closed\","
            + "\"zenrows_params\":{\"js_render\":\"true\"},"
            + "\"tasks\":["
            + "{\"url\":\"https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie\"},"
            + "{\"url\":\"https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket\"}"
            + "]}";
        String response = Request.post("https://async.api.zenrows.com/v1/jobs")
                .addHeader("X-API-Key", "YOUR_ZENROWS_API_KEY")
                .bodyString(body, ContentType.APPLICATION_JSON)
                .execute().returnContent().asString();
        System.out.println(response);
    }
}
```

```php PHP theme={"theme":"css-variables"}
<?php
$payload = json_encode([
    'type' => 'regular',
    'status' => 'closed',
    'zenrows_params' => ['js_render' => 'true'],
    'tasks' => [
        ['url' => 'https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie'],
        ['url' => 'https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket'],
    ],
]);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://async.api.zenrows.com/v1/jobs');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_ZENROWS_API_KEY', 'Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec($ch);
echo $response . PHP_EOL;
curl_close($ch);
?>
```

```go Go theme={"theme":"css-variables"}
package main

import (
    "bytes"
    "io"
    "log"
    "net/http"
)

func main() {
    payload := []byte(`{
        "type": "regular",
        "status": "closed",
        "zenrows_params": { "js_render": "true" },
        "tasks": [
            { "url": "https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie" },
            { "url": "https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket" }
        ]
    }`)
    req, err := http.NewRequest("POST", "https://async.api.zenrows.com/v1/jobs", bytes.NewBuffer(payload))
    if err != nil {
        log.Fatalln(err)
    }
    req.Header.Set("X-API-Key", "YOUR_ZENROWS_API_KEY")
    req.Header.Set("Content-Type", "application/json")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatalln(err)
    }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    log.Println(string(body))
}
```

```ruby Ruby theme={"theme":"css-variables"}
# gem install faraday
require 'faraday'
require 'json'

payload = {
    type: 'regular',
    status: 'closed',
    zenrows_params: { js_render: 'true' },
    tasks: [
        { url: 'https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie' },
        { url: 'https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket' }
    ]
}
conn = Faraday.new
res = conn.post('https://async.api.zenrows.com/v1/jobs') do |req|
    req.headers['X-API-Key'] = 'YOUR_ZENROWS_API_KEY'
    req.headers['Content-Type'] = 'application/json'
    req.body = payload.to_json
end
print(res.body)
```

```bash cURL theme={"theme":"css-variables"}
curl -X POST "https://async.api.zenrows.com/v1/jobs" \
  -H "X-API-Key: YOUR_ZENROWS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "regular",
    "status": "closed",
    "zenrows_params": { "js_render": "true" },
    "tasks": [
      { "url": "https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie" },
      { "url": "https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket" }
    ]
  }'
```

The response includes a `job_id` and the initial run status. Poll `GET /jobs/{id}` until `latest_run.status` reaches a **terminal** state (`completed`, `stopped` or `failed`), then collect the results. A run that ends `failed` stopped for an account reason, such as running out of credits; its `failure_reason` and `failure_detail` say which.

### Get your results

Once the run is complete, list the successful tasks and download each one's scraped content. Every result row carries a `result_url`, a presigned link to the scraped page that is valid for 2 hours. Replace `JOB_ID` with the `job_id` from the submit response.

```python Python theme={"theme":"css-variables"}
## pip install requests
import requests

headers = {'X-API-Key': 'YOUR_ZENROWS_API_KEY'}
page = requests.get('https://async.api.zenrows.com/v1/jobs/JOB_ID/results',
                    headers=headers, params={'status': 'successful'}).json()
for row in page['results']:
    if not row.get('result_url'):
        continue  # expired: past its 14-day availability window
    html = requests.get(row['result_url']).text  # the scraped page
    print(row.get('external_id') or row['task_id'], len(html), 'chars')
```

```javascript Node.js theme={"theme":"css-variables"}
// npm install axios
const axios = require('axios');

async function main() {
    const page = (await axios.get('https://async.api.zenrows.com/v1/jobs/JOB_ID/results', {
        headers: { 'X-API-Key': 'YOUR_ZENROWS_API_KEY' },
        params: { status: 'successful' },
    })).data;
    for (const row of page.results) {
        if (!row.result_url) continue; // expired: past its 14-day availability window
        const html = (await axios.get(row.result_url)).data; // the scraped page
        console.log(row.external_id ?? row.task_id, String(html).length, 'chars');
    }
}

main();
```

```java Java theme={"theme":"css-variables"}
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.hc.client5.http.fluent.Request;

public class GetResults {
    public static void main(final String... args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        JsonNode page = mapper.readTree(
                Request.get("https://async.api.zenrows.com/v1/jobs/JOB_ID/results?status=successful")
                        .addHeader("X-API-Key", "YOUR_ZENROWS_API_KEY")
                        .execute().returnContent().asString());
        for (JsonNode row : page.path("results")) {
            if (!row.hasNonNull("result_url")) continue; // expired
            String html = Request.get(row.path("result_url").asText())
                    .execute().returnContent().asString(); // the scraped page
            String id = row.path("external_id").asText(row.path("task_id").asText());
            System.out.println(id + " " + html.length() + " chars");
        }
    }
}
```

```php PHP theme={"theme":"css-variables"}
<?php
$ch = curl_init('https://async.api.zenrows.com/v1/jobs/JOB_ID/results?status=successful');
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: YOUR_ZENROWS_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$page = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($page['results'] as $row) {
    if (empty($row['result_url'])) continue; // expired
    $html = file_get_contents($row['result_url']); // the scraped page
    echo ($row['external_id'] ?? $row['task_id']) . ' ' . strlen($html) . ' chars' . PHP_EOL;
}
?>
```

```go Go theme={"theme":"css-variables"}
package main

import (
    "encoding/json"
    "io"
    "log"
    "net/http"
)

func main() {
    req, _ := http.NewRequest("GET", "https://async.api.zenrows.com/v1/jobs/JOB_ID/results?status=successful", nil)
    req.Header.Set("X-API-Key", "YOUR_ZENROWS_API_KEY")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Fatalln(err)
    }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    var page struct {
        Results []struct {
            TaskID     string `json:"task_id"`
            ExternalID string `json:"external_id"`
            ResultURL  string `json:"result_url"`
        } `json:"results"`
    }
    json.Unmarshal(body, &page)
    for _, row := range page.Results {
        if row.ResultURL == "" {
            continue // expired: past its 14-day availability window
        }
        r, _ := http.Get(row.ResultURL) // the scraped page
        html, _ := io.ReadAll(r.Body)
        r.Body.Close()
        name := row.ExternalID
        if name == "" {
            name = row.TaskID
        }
        log.Println(name, len(html), "chars")
    }
}
```

```ruby Ruby theme={"theme":"css-variables"}
# gem install faraday
require 'faraday'
require 'json'

page = JSON.parse(Faraday.get('https://async.api.zenrows.com/v1/jobs/JOB_ID/results?status=successful') { |req|
    req.headers['X-API-Key'] = 'YOUR_ZENROWS_API_KEY'
}.body)
page['results'].each do |row|
    next unless row['result_url'] # expired
    html = Faraday.get(row['result_url']).body # the scraped page
    puts "#{row['external_id'] || row['task_id']} #{html.length} chars"
end
```

```bash cURL theme={"theme":"css-variables"}
# 1) List the successful results; each row has a presigned result_url valid 2h.
curl "https://async.api.zenrows.com/v1/jobs/JOB_ID/results?status=successful" \
  -H "X-API-Key: YOUR_ZENROWS_API_KEY"

# 2) Download one result's scraped HTML using its result_url from the response above.
curl "RESULT_URL"
```

> [!TIP]
>
> Want to see the cost before you run anything? You can estimate credits client-side with no API call. See [Estimate cost](https://docs.zenrows.com/batch/developer-guide-restapi.md#estimate-cost).

## Next steps

> [card] [API Reference](https://docs.zenrows.com/batch/developer-guide-restapi.md)
>
> Every endpoint: open jobs, CSV upload, scheduling, webhooks, and more.

> [card] [Python SDK](https://docs.zenrows.com/batch/sdk/python.md)
>
> The same flow in a few lines of Python. Node.js and Go SDKs are also available.

> [card] [Troubleshooting](https://docs.zenrows.com/batch/troubleshooting.md)
>
> Diagnose authentication, submission, download, and webhook issues fast.

> [card] [FAQ](https://docs.zenrows.com/batch/faq.md)
>
> Quick answers on access, pricing, limits, and scraping options.


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