Skip to main content
Glama

scrapewise_run_scraper

        Triggers a manual run of the scraper identified by `id`. The run is queued
        on the scheduler and starts asynchronously — this call returns immediately
        once the run is accepted, NOT when scraping completes. Long scrapes can take
        minutes to hours; poll `scrapewise_get_scraper_load_history` to check status,
        or read `scrapewise_get_scraper.lastRunState` for the most-recent state of
        this specific scraper.

        Args:
          - id (string, path param, required): the scraper's MongoDB ObjectId. Get
            from `scrapewise_get_scraper_list` or `scrapewise_get_scraper_group_list`.
          - customerUniqueRef (string, query param, optional): admin-only escape hatch
            to run another customer's scraper from a customer-switch session. Leave
            unset for normal runs as the authenticated customer.
          - continueFromJobId (string, query param, optional, website email lists only):
            Continue. The id of the job that stopped at a limit (stoppedReason TIME_LIMIT
            or DAILY_LIMIT, continuable true in scrapewise_get_scraper_load_history). Only
            the websites not read yet are read and charged. Refused with 409
            NOT_CONTINUABLE (nothing started) when that job is not the list's latest job or
            nothing is left to read. Omit it for a plain run.

        Returns:
          200 OK with `{"firstJob": boolean}` — true only when a signed-in user starts their very
          first run by hand; always false for API keys. The run is queued asynchronously — poll
          `scrapewise_get_scraper_load_history` for the new run's state, or read
          `scrapewise_get_scraper.lastRunState` for the most-recent state of this scraper.
          The run will be PENDING immediately after this returns, then transitions to
          RUNNING and COMPLETED / FAILED / STOPPED.

        Examples:
          - Use when: "start the mototas scraper" → list to find id, then run with that id
          - Use when: "re-run scraper {id} now" → run with id
          - Don't use when: the scraper is already RUNNING → call scrapewise_stop_scraper
              first to cancel the in-flight run, then re-run
          - Don't use when: you want to run all scrapers in a group → use
              scrapewise_run_scraper_group with the group id (more efficient)
          - Don't use when you are looping this call over a list of scrapers you just
              created, one per URL. Do NOT create one scraper per URL: give ONE scraper
              the whole list — `scrapewise_run_scraper_url_list` creates it, stores the
              list and runs it in one call.

        Website email lists (endpoint websitecontacts): with continueFromJobId this call is
        Continue. A list whose job stopped at the job-time limit (stoppedReason TIME_LIMIT,
        23 hours by default) or at the daily limit (DAILY_LIMIT, after 00:00 UTC) reads ONLY
        the websites not read yet, in the same run chain; nothing already read is fetched or
        charged again. Nothing is ever continued by itself.

        Error Handling:
          - 402 if customer plan lacks MANUAL_RUN feature.
          - 400 (CustomerError envelope) if no scraper with the given id exists for this
            customer, OR if the scraper is currently RUNNING / PENDING (code
            ALREADY_RUNNING), OR if it is disabled (code SCRAPER_DISABLED).
          - 409 NOT_CONTINUABLE if continueFromJobId names a job that has nothing left to
            continue (not the list's latest job, the list is read, or not this account's).
            Nothing was started or charged.
          - 409 LIST_RESUME_OFF if a website email list cannot be continued right now
            (nothing was started).
          - 401 Unauthorized if no valid Authorization header.
          - 500 INTERNAL on unexpected server error.

[runtime hint] This tool returns JSON-as-text — its response shape is dynamic (per-scraper itemsConfig, file binary, etc.) so the MCP outputSchema is omitted. Do not rely on the presence of any specific field in the response; treat the result as a string-or-object blob and parse defensively.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>"
    },
    "name": "scrapewise_run_scraper"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesthe scraper's MongoDB ObjectId. Get from `scrapewise_get_scraper_list` or `scrapewise_get_scraper_group_list`.
continueFromJobIdNoContinue. The id of the job that stopped at a limit (stoppedReason TIME_LIMIT or DAILY_LIMIT, continuable true in scrapewise_get_scraper_load_history). Only the websites not read yet are read and charged. Refused with 409 NOT_CONTINUABLE (nothing started) when that job is not the list's latest job or nothing is left to read. Omit it for a plain run.
customerUniqueRefNoadmin-only escape hatch to run another customer's scraper from a customer-switch session. Leave unset for normal runs as the authenticated customer.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / continueFromJobId / description
      Added value: +"Continue. The id of the job that stopped at a limit (stoppedReason TIME_LIMIT or DAILY_LIMIT, continuable true in scrapewise_get_scraper_load_history). Only the websites not read yet are read and charged. Refused with 409 NOT_CONTINUABLE (nothing started) when that job is not the list's latest job or nothing is left to read. Omit it for a plain run."
    • addedInput schema / properties / customerUniqueRef / description
      Added value: +"admin-only escape hatch to run another customer's scraper from a customer-switch session. Leave unset for normal runs as the authenticated customer."
    • addedInput schema / properties / id / description
      Added value: +"the scraper's MongoDB ObjectId. Get from `scrapewise_get_scraper_list` or `scrapewise_get_scraper_group_list`."
  2. Added

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only say non-read-only, non-idempotent, open-world; the description goes well beyond by disclosing that the run is queued and returns immediately, the PENDING → RUNNING → COMPLETED/FAILED/STOPPED lifecycle, that continuation reads and charges only unread websites, and a full error-code table (402 plan gate, 400 ALREADY_RUNNING/SCRAPER_DISABLED, 409 NOT_CONTINUABLE/LIST_RESUME_OFF). It also flags the credit-charging consequence, 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.

Conciseness3/5

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

Front-loaded correctly and sectioned (Args / Returns / Examples / Error Handling), but it repeats itself: the async-and-poll instruction appears twice, and continueFromJobId continuation semantics are spelled out in Args and again in a dedicated "Website email lists" paragraph. Roughly a third of the text is duplication of already-stated material.

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 mutation tool with no output schema, it covers everything an agent needs: return shape ({"firstJob": boolean}), the fact that the real result must be polled, how to resolve the id, failure modes, and sibling routing. The runtime hint about a dynamic blob response is consistent with the "poll for state" guidance rather than undermined by it.

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 description coverage is 100% and the Args block largely restates the field descriptions verbatim, including the continueFromJobId refusal conditions. It does add workflow meaning (where to obtain the job id and what stoppedReason/continuable mean in scrapewise_get_scraper_load_history), but for the two optional params the gain over the schema is marginal, so baseline 3 holds.

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?

Opens with a specific verb+resource ("Triggers a manual run of the scraper identified by `id`") and immediately qualifies the scope with the async contract. It distinguishes itself from siblings by name — run_scraper_group, run_scraper_url_list, stop_scraper — so an agent can route without opening any schema.

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

Usage Guidelines5/5

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

Explicit "Use when" / "Don't use when" pairs cover the main decision points: already-RUNNING (use stop first), group runs (use run_scraper_group), and looping over URLs (use run_scraper_url_list instead). The alternative tool is named for each exclusion rather than left to inference.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.