Spicrawl

List batch jobs

spicrawl_batch_list

Read-onlyIdempotent

List this API key's project's batch jobs, newest first, with status and progress. Returns { batches: [...], next_cursor? }; pass next_cursor back as cursor for the next page.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Page size (default 50, max 200).
`cursor`	No	`next_cursor` from a previous page, verbatim.
`status`	No	Only jobs in this status.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`batches`	Yes	Jobs, newest first (empty when there are none).
`next_cursor`	No	Pass back as `cursor` for the next page; absent on the last page.

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": {
+    "batches": {
+      "description": "Jobs, newest first (empty when there are none).",
+      "items": {
+        "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"
+      },
+      "type": "array"
+    },
+    "next_cursor": {
+      "description": "Pass back as `cursor` for the next page; absent on the last page.",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "batches"
+  ],
+  "type": "object"
+}

First observedOct 1, 2026

TDQS

A3.6/5.0

Behavior4/5

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

Annotations already declare the safe-read profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real context beyond them: project scoping, newest-first ordering, and the cursor-based pagination contract, which an agent needs to page correctly.

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?

Two tight sentences, front-loaded with purpose and scope, then the return/pagination contract. No filler; every clause earns its place.

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

Completeness4/5

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

An output schema exists, so explaining return values is optional, yet the description still sketches the shape and pagination loop usefully. It is complete for calling the tool; the only gap is that sibling boundaries (vs batch_status) are not drawn.

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 all three parameters are already documented, including the status enum. The description reinforces the cursor linkage but adds no syntax or meaning beyond what the schema states, so baseline 3 applies.

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+resource ('List ... batch jobs') with clear scope (this API key's project) and ordering (newest first). However, it does not differentiate itself from the sibling spicrawl_batch_status, which likely also surfaces job status, so an agent may hesitate between the two.

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

Usage Guidelines2/5

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

No explicit when-to-use versus alternatives is given. The pagination instruction ('pass next_cursor back as cursor') is procedural help, not guidance on selecting this tool over batch_status or batch_results.

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

Give agents eyes on the webHosted screenshot MCP. Send a URL, get a pixel-perfect image. $0.002 per grab. Works with Claude, Cursor, and Codex.grabbit.liveAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?