Batch

`POST https://api.keirolabs.cloud/api/v2/search/batch`

Cost: 0.5 credits paid · 1 free per query · Latency: Async

Submit up to 75 search queries in a single async job. The POST returns a job ID immediately; poll the GET endpoint until the job reaches completed (or failed/partial). Polling is free of charge and rate-limited separately. Jobs are accessible for 1 hour after submission.

**When to use it.** Use Batch when you need to run many searches (1-75) asynchronously. Submit the job, poll for results. Costs 1 credit/query (0.5 on Essential and Pro, free on Startup). Ideal for bulk SERP analysis, keyword research, and data pipelines.

**When not to.** Don't use Batch for a single query (use Search — simpler and faster). Don't use if you need content extraction (Batch only returns SERP results, not page content).

## Request

**cURL**

```bash
curl -X POST https://api.keirolabs.cloud/api/v2/search/batch \
  -H "Authorization: Bearer $KEIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries": ["python web scraping", "golang concurrency", "react hooks tutorial"], "maxResults": 10}'
```

**Python**

```python
import os, requests

res = requests.post(
    "https://api.keirolabs.cloud/api/v2/search/batch",
    headers={"Authorization": f"Bearer {os.environ['KEIRO_API_KEY']}"},
    json={
        "queries": [
            "python web scraping",
            "golang concurrency",
            "react hooks tutorial"
        ],
        "maxResults": 10
    },
)
print(res.json())
```

**Node.js**

```js
const res = await fetch("https://api.keirolabs.cloud/api/v2/search/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KEIRO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "queries": [
      "python web scraping",
      "golang concurrency",
      "react hooks tutorial"
    ],
    "maxResults": 10
  }),
});
console.log(await res.json());
```

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `queries` | string[] | yes | Array of queries (1-75 per submission, server-clamped). Each query is 1-500 chars. Empty/invalid entries are filtered out before processing. |
| `maxResults` | integer | no | Results per query. Default: 10. Max: 50 (server-clamped). |

## Response

```json title="200 OK"
{
  "id": "29938885db05eca3",
  "status": "processing",
  "total": 3,
  "message": "batch submitted, poll GET /api/v2/search/batch/29938885db05eca3",
  "creditsCharged": 0.5,
  "creditsRemaining": 1136
}
```

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | Job ID. Poll GET /api/v2/search/batch/{id} to check status. |
| `status` | string | no | Job status: "processing", "completed", "failed", or "partial". |
| `total` | integer | no | Total number of queries in the batch. |
| `message` | string | no | Human-readable status message with polling URL. |
| `creditsCharged` | number | no | Credits charged (0.5/query for paid, 1/query for free). |
| `creditsRemaining` | number | no | Your remaining credit balance. |

## Polling for results

Submitting returns a job id. Poll `GET /api/v2/search/batch/:id` until the job is done.

```bash
curl https://api.keirolabs.cloud/api/v2/search/batch/$JOB_ID \
  -H "Authorization: Bearer $KEIRO_API_KEY"
```

## Errors

| Status | Code | Cause | Fix |
| --- | --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Missing queries array or too many queries | Provide 1-75 queries as a string array. |
| `401` | `UNAUTHORIZED` | Missing or invalid API key | Check your Authorization: Bearer header. |
| `402` | `INSUFFICIENT_CREDITS` | Not enough credits for all queries | Need 1 credit per query (0.5 on Essential and Pro; free on Startup). |
| `403` | `PLAN_UPGRADE_REQUIRED` | Batch requires a paid plan (or a balance of 1,000+ credits) | Upgrade to Starter or buy more credits at /dashboard/billing. |
| `429` | `RATE_LIMIT_EXCEEDED` | Too many batch submissions | Batch is rate-limited per hour. Check Retry-After header. |

## Rate limits

| Tier | Limit |
| --- | --- |
| Free | Not available |
| Starter | 10/hour |
| Pro | 25/hour |
| Startup | 50/hour |
| Enterprise | 200/hour |

Over the limit you get a `429`. See [Rate limits](/rate-limits) for headers and backoff.