Spicrawl

Cancel a batch job

spicrawl_batch_cancel

DestructiveIdempotent

Cancel a batch job: items not yet started are cancelled and will never run; items already finished keep their results; items already running finish first, so the job comes back cancelling and moves to cancelled when they drain. Cannot be undone — resubmit to run the URLs again. Returns the job object.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`job_id`	Yes	The batch job id returned by spicrawl_batch_submit or spicrawl_batch_list.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Job id. Pass it as `job_id` to the other spicrawl_batch_* tools.
`name`	No	The label given at submission, if any.
`open`	No	True while the job accepts appended items (it will not complete until closed).
`params`	No	The job-level scrape settings as stored.
`status`	No	Lifecycle: queued, running, paused, cancelling, completed, failed or cancelled. Keep polling while queued/running/paused/cancelling; stop at completed, failed or cancelled.
`priority`	No	Effective scheduling priority.
`progress`	No	Live item counters and the credits charged so far.
`warnings`	No	Decisions made on the caller's behalf at submission (a clamped concurrency, items not yet queued).
`error_code`	No	Machine code of a job-level failure.
`project_id`	No	Project the API key belongs to.
`started_at`	No	ISO-8601 time the first item started.
`status_url`	No	API path to poll for this job: /v1/batch/{id}.
`concurrency`	No	Effective per-job concurrency after the server's clamping.
`finished_at`	No	ISO-8601 time the job reached a terminal status.
`results_url`	No	API path of the job's results: /v1/batch/{id}/results.
`total_items`	No	Number of items in the job.
`max_attempts`	No	Effective attempts per item.
`submitted_at`	No	ISO-8601 time the job was accepted.
`error_message`	No	Human-readable job-level failure reason.
`estimated_credits`	No	Credits reserved at submission (a hold, not a charge; compare with progress.credits_charged).
`failure_threshold`	No	Failed-item count that aborts the job, when set.
`results_expire_at`	No	ISO-8601 deadline after which results answer 410 Gone.
`cancel_requested_at`	No	ISO-8601 time a cancel was accepted.
`estimated_credits_micro`	No	Same as estimated_credits in micro-credits.

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": {
+    "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"
+}

First observedOct 1, 2026

TDQS

A4/5.0

Behavior5/5

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

Goes well beyond the annotations (destructiveHint, idempotentHint, readOnlyHint=false) by specifying exactly what is destroyed (items not yet started), what is preserved (finished items keep results), and how in-flight items are handled. It also discloses irreversibility, the 'cancelling' -> 'cancelled' state transition, and the recovery path (resubmit), which annotations cannot express.

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

Conciseness4/5

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

Front-loaded with the core action and packed with high-value behavioral detail in a compact form; no filler sentences. The trailing 'Returns the job object' is mildly redundant given an output schema exists, a minor inefficiency rather than a flaw.

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?

For a single-parameter mutation tool with full annotation coverage and an output schema, the description supplies everything else an agent needs: scope of destruction, state-machine behavior, irreversibility, and remediation. No meaningful gap remains.

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?

Only one parameter, job_id, and the schema documents it fully (100% coverage, including its provenance from spicrawl_batch_submit/spicrawl_batch_list). The description adds no format, constraint, or edge-case detail about the id, so baseline 3 is appropriate when the schema already carries the parameter contract.

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

Purpose4/5

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

States a specific verb and resource ('Cancel a batch job') and immediately scopes the semantics to per-item lifecycle behavior, so an agent knows exactly what operation this is. It never names or contrasts the adjacent spicrawl_batch_close sibling, which is the one plausible confusion, so it falls short of full sibling differentiation.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: the description communicates that this stops a job and that running items must drain, which tells an agent the appropriate operational moment. However there is no explicit when-to-use/when-not, no prerequisites, and no mention of when spicrawl_batch_close or spicrawl_batch_retry would be preferred instead.

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?