POST /batches
Submit up to 1,000 URLs as one capture batch, all under one script and one browser profile.
Syntax
POST https://grid-lab.zyxio.xyz/batches
x-api-key: <key>
content-type: application/json
{"urls": ["<url>", ...], "script": "<script>", "profileId": "<profile>", "params": {...}, "priority": <n>}Request
| Name | Where | Required | Meaning |
|---|---|---|---|
x-api-key | header | yes, or Authorization | Your API key. An MCP client signed in with Zyxio sends Authorization: Bearer <token> instead. |
urls | body | yes | 1 to 1,000 absolute URLs. Each becomes one item. |
script | body | no | capture (default), fetch, browser-fetch or render-fetch. See Captures. |
profileId | body | no | desktop-chrome-nl/v2 (default) or native-headless-chromium/v2. |
params | body | no | The script's parameters, such as allowedHosts for browser-fetch and render-fetch. Checked when each item runs. Default {}. |
priority | body | no | 1 to 1,000,000; lower runs sooner. Items without a priority run before any item that has one. |
Any other field is refused.
Response
201 Created
| Field | Meaning |
|---|---|
batchId | The batch's id. Poll it with GET /batches/{batchId}. |
jobCount | The number of items, one per URL. |
Errors
| Status | Body | When | What to do |
|---|---|---|---|
400 | {"error": "invalid batch body", "detail": [...]} | No urls, more than 1,000, a URL that does not parse, an unknown script, profile or field. detail lists each problem. | Fix the body. |
401 | {"error": "unauthorized"} | No credential, or a key that is revoked, expired, wrong, or of a suspended account. | Send a valid key. |
503 | {"error": "accounting_unavailable"} | Your key or Zyxio sign-in could not be checked because the account database did not answer in time. Nothing was done. | Retry shortly; the same request is safe to resend. |
402 | {"error": "insufficient_credit", "requiredMicros": ..., "availableMicros": ...} | Your account is metered, credit enforcement is on, and the batch's reservation exceeds your available credit (with monthly invoicing: what your monthly limit and the unpaid-usage ceiling leave; nothing while invoicing is paused or an invoice is past due). Nothing was queued. | Top up, raise your monthly limit or pay the past-due invoice, or send fewer URLs. |
402 | {"error": "daily_cap_exceeded", ...} | The key's daily cap would be exceeded. Nothing was queued. | Raise the cap on the panel, or wait for 00:00 UTC. |
403 | {"error": "forbidden"} | A valid Zyxio sign-in token whose identity has no account here, or whose account is suspended. | Accept your invitation first, or use a key. |
403 | {"error": "account_suspended"} | Credit enforcement is on and the account a Zyxio-internal credential is billed to is suspended. Nothing was queued. (A suspended customer's own keys and sign-in are refused before this, with 401 and 403 forbidden.) | Ask Zyxio. |
Example
curl -s https://grid-lab.zyxio.xyz/batches \
-H "x-api-key: $BROWSERGRID_API_KEY" \
-H "content-type: application/json" \
-d '{"urls": ["https://example.com/", "https://example.com/about"], "script": "render-fetch", "params": {"allowedHosts": ["example.com"]}}'{"batchId": "6f1d2c3e-8a4b-4e5f-9a0b-1c2d3e4f5a6b", "jobCount": 2}Billing
At submission the batch reserves its item count times the script's price: fetch 120 µ€, browser-fetch and render-fetch 800 µ€, capture 1,000 µ€ per item. The example reserves 1,600 µ€ (€0.0016).
Each item settles on its own. It is charged its price once, when its files are published. An item that fails after its last attempt is released and costs nothing; our own retries are free. Items are settled by a periodic pass over the grid's records, so a charge, and the release of what an item did not use, appears up to one settlement interval (30 seconds) after the item finishes.
See also
Captures, GET /batches/{batchId}, GET /artifacts/{jobId}/{kind}, Credit and billing.