Spicrawl

Add URLs to an open batch job

spicrawl_batch_add_items

Append URLs to a batch job that was submitted with open: true. Same item vocabulary as spicrawl_batch_submit (EITHER urls or items, not both, plus shared settings for these new items). Fails with CONFLICT if the job is closed or finished. Not idempotent: calling twice adds the URLs twice. Returns { job, items_added, items_dispatched }.

Input Schema

TableJSON Schema

Name	Required	Description
`urls`	No	Shorthand: URLs scraped with the shared settings and no per-item overrides. Mutually exclusive with `items`.
`wait`	No	Milliseconds to wait after load (rendered scrapes).
`items`	No	Long form: one /v1/scrape request object per item. Besides `url` and `external_id`, any /v1/scrape field (e.g. `js_render`, `wait_for`, `response_format`) overrides the shared setting for that item only. Mutually exclusive with `urls`.
`format`	No	Output format for every item (`response_format`). spicrawl_batch_submit defaults to 'markdown', the same as spicrawl_scrape; an item's own `response_format` overrides it.
`job_id`	Yes	The batch job id returned by spicrawl_batch_submit or spicrawl_batch_list.
`render`	No	Render every URL with a browser (`js_render`).
`max_cost`	No	Ceiling in credits for ONE item (not the whole job — see credit_budget).
`wait_for`	No	CSS selector to wait for before capturing (rendered scrapes).
`premium_proxy`	No	Coming soon: not available yet, do not send. Use residential managed-pool exits for every URL.
`proxy_country`	No	Coming soon: not available yet, do not send. ISO-3166 alpha-2 exit country; requires premium_proxy.
`custom_headers`	No	Extra request headers sent with every URL.
`block_resources`	No	Resource types to block while rendering, e.g. ["image","font","media"].
`main_content_only`	No	Strip each page to its main article.

Output Schema

TableJSON Schema

Name	Required	Description
`job`	No	The job as it stands after the call.
`items_added`	No	Items written to the job.
`items_dispatched`	No	Of those, how many reached the dispatch queue now; do not re-add the rest.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 13, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "items_added": {
+      "description": "Items written to the job.",
+      "type": "number"
+    },
+    "items_dispatched": {
+      "description": "Of those, how many reached the dispatch queue now; do not re-add the rest.",
+      "type": "number"
+    },
+    "job": {
+      "additionalProperties": true,
+      "description": "The job as it stands after the call.",
+      "properties": {
+        "cancel_requested_at": {
+          "description": "ISO-8601 time a cancel was accepted.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "concurrency": {
+          "description": "Effective per-job concurrency after the server's clamping.",
+          "type": "number"
+        },
+        "error_code": {
+          "description": "Machine code of a job-level failure.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error_message": {
+          "description": "Human-readable job-level failure reason.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "estimated_credits": {
+          "description": "Credits reserved at submission (a hold, not a charge; compare with progress.credits_charged).",
+          "type": "number"
+        },
+        "estimated_credits_micro": {
+          "description": "Same as estimated_credits in micro-credits.",
+          "type": "number"
+        },
+        "failure_threshold": {
+          "description": "Failed-item count that aborts the job, when set.",
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "finished_at": {
+          "description": "ISO-8601 time the job reached a terminal status.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "description": "Job id. Pass it as `job_id` to the other spicrawl_batch_* tools.",
+          "type": "string"
+        },
+        "max_attempts": {
+          "description": "Effective attempts per item.",
+          "type": "number"
+        },
+        "name": {
+          "description": "The label given at submission, if any.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "open": {
+          "description": "True while the job accepts appended items (it will not complete until closed).",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "params": {
+          "anyOf": [
+            {
+              "additionalProperties": {},
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The job-level scrape settings as stored."
+        },
+        "priority": {
+          "description": "Effective scheduling priority.",
+          "type": "number"
+        },
+        "progress": {
+          "additionalProperties": true,
+          "description": "Live item counters and the credits charged so far.",
+          "properties": {
+            "bytes": {
+              "description": "Total response bytes of finished items.",
+              "type": "number"
+            },
+            "cancelled": {
+              "description": "Items not run because the job was cancelled.",
+              "type": "number"
+            },
+            "completed": {
+              "description": "Items in any terminal status (succeeded + failed + cancelled + skipped).",
+              "type": "number"
+            },
+            "credits_charged": {
+              "description": "Credits actually charged so far (whole credits, rounded down).",
+              "type": "number"
+            },
+            "credits_charged_micro": {
+              "description": "Same as credits_charged in micro-credits (1 credit = 1,000,000).",
+              "type": "number"
+            },
+            "failed": {
+              "description": "Items that failed after all attempts; re-run them with spicrawl_batch_retry.",
+              "type": "number"
+            },
+            "percent_complete": {
+              "description": "completed / total x 100.",
+              "type": "number"
+            },
+            "remaining": {
+              "description": "Items not yet finished (total - completed).",
+              "type": "number"
+            },
+            "skipped": {
+              "description": "Items skipped (for example after failure_threshold or credit_budget stopped the run).",
+              "type": "number"
+            },
+            "succeeded": {
+              "description": "Items that succeeded. Only these are charged.",
+              "type": "number"
+            },
+            "total": {
+              "description": "Items in the job (grows when items are appended to an open job).",
+              "type": "number"
+            }
+          },
+          "type": "object"
+        },
+        "project_id": {
+          "description": "Project the API key belongs to.",
+          "type": "string"
+        },
+        "results_expire_at": {
+          "description": "ISO-8601 deadline after which results answer 410 Gone.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "results_url": {
+          "description": "API path of the job's results: /v1/batch/{id}/results.",
+          "type": "string"
+        },
+        "started_at": {
+          "description": "ISO-8601 time the first item started.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "status": {
+          "description": "Lifecycle: queued, running, paused, cancelling, completed, failed or cancelled. Keep polling while queued/running/paused/cancelling; stop at completed, failed or cancelled.",
+          "type": "string"
+        },
+        "status_url": {
+          "description": "API path to poll for this job: /v1/batch/{id}.",
+          "type": "string"
+        },
+        "submitted_at": {
+          "description": "ISO-8601 time the job was accepted.",
+          "type": "string"
+        },
+        "total_items": {
+          "description": "Number of items in the job.",
+          "type": "number"
+        },
+        "warnings": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Decisions made on the caller's behalf at submission (a clamped concurrency, items not yet queued)."
+        }
+      },
+      "required": [
+        "id"
+      ],
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedOct 13, 2026

removedInput schema / properties / engine

Removed value: -{
-  "description": "Pin the scrape engine for every item: `fetch` or `obscura` (must be allowed by the plan and served by the deployment); `camoufox` is coming soon, do not pin it yet. `chromium` cannot be pinned in a batch — use `render: true`, or spicrawl_scrape.",
-  "enum": [
-    "fetch",
-    "obscura",
-    "camoufox"
-  ],
-  "type": "string"
-}

First observedOct 1, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond annotations by disclosing the non-idempotency ('calling twice adds the URLs twice'), the CONFLICT failure for closed/finished jobs, and the exact return shape. Annotations already cover idempotentHint=false and openWorldHint, so credit here is for the conflict semantics and return fields.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four dense sentences with zero filler: purpose, vocabulary constraint, failure condition, idempotency warning, and return shape. The critical non-idempotency warning is front-loaded enough to be caught.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the operation's key gotchas (mutual exclusivity, CONFLICT on closed jobs, non-idempotency) despite an output schema existing. An agent has everything needed to invoke correctly and interpret the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema carries the parameter burden. The description adds value by flagging the mutual exclusivity of `urls`/`items` and that shared settings apply to new items, but this largely restates what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (append) and resource (URLs to a batch job), and scopes it precisely to jobs submitted with `open: true`, which distinguishes it from spicrawl_batch_submit and other batch siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the sibling it shares item vocabulary with (spicrawl_batch_submit) and states the precondition (job must be open) plus failure mode (CONFLICT). Lacks explicit 'when to use this vs spicrawl_batch_retry' guidance, but the open-job scoping is a clear routing signal.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Spicrawl tools Inspect

Try in Browser

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?