Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to MrScraper

Scalekit connector
Open markdown

The MrScraper connector lets your AI agent act in each user's MrScraper account. Each user connects their own MrScraper API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 19 tools.

Tools
19
What they doRead · write · destructive
6 · 13 · 06 read13 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the MrScraper connection

    In AgentKit > Connections, create a MrScraper connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'mrscraper'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize MrScraper:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'mrscraper_verify_api_token',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their MrScraper credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • mrscraper_get_analytic_statusesGet scrape status counts for one domain within a date range, for one action label, optionally filtered by API token name.Read-only

    Get Analytic Statuses

    Get scrape status counts for one domain within a date range, for one action label, optionally filtered by API token name. Returns a summary with countAll, successRate, reqPerMinute and avgLatency, plus a list of key and value pairs counting scrapes by status (COMPLETED, PENDING and FAILED came back in testing, with the counts as strings). Use this to see how scraping for a domain is performing over a period (the dates carry no timezone parameter, and the timezone MrScraper applies was not tested). Use mrscraper_list_results to inspect individual results and mrscraper_get_proxy_bandwidth for proxy bandwidth.

    Inputs

    actionstringrequired
    The action label of the scrapes to count: the value sent as the action parameter on Scraper API calls. Scrapes sent with a label were counted under it in testing (a read right after the calls showed 0 and a later read showed the counts). The vendor reference describes the label as routing a scrape to a scraper action or simply flagging it, useful for separating analytics per domain; routing was not observed. Required: the live API rejects requests without it ('action must be a string') although the vendor docs list it as optional. Example: product-pages
    domainstringrequired
    Domain to aggregate scrape statuses for. Example: example.com
    endDatestringrequired
    End of the date range, in yyyy-MM-dd HH:mm:ss format. The timezone MrScraper applies was not tested. Example: 2026-04-13 23:59:59
    startDatestringrequired
    Start of the date range, in yyyy-MM-dd HH:mm:ss format. The timezone MrScraper applies was not tested. Example: 2026-04-12 00:00:00
    apiTokenNamestring
    Optional name of an API token. Per the vendor reference, only scrapes made with the token of this name are counted and leaving it out counts all tokens; this filter was not observed (a call with a guessed token name was accepted, and counts with and without it were not compared). Example: production-worker
  • mrscraper_get_proxy_bandwidthGet the total proxy bandwidth used per proxy username within a date range, optionally limited to one region.Read-only

    Get Proxy Bandwidth

    Get the total proxy bandwidth used per proxy username within a date range, optionally limited to one region. Returns the usage list under the key array, with one entry per proxy username, each holding the username and its total bandwidth usage (username, total_bandwidth_usage) for the range as a number with no documented unit. Use this to see how much proxy traffic each proxy user consumed. Use mrscraper_get_analytic_statuses for scrape status counts and mrscraper_verify_api_token for token usage against the token limit. Requires an active MrScraper Proxy subscription: without one the API answers 403 with the message "You don't have an active Proxy subscription. Please subscribe to access this feature." No successful call was possible in testing, so the response shape comes from the vendor reference.

    Inputs

    endDatestringrequired
    End of the date range, in yyyy-MM-dd HH:mm:ss format. Read in the timezone given by timezone when one is supplied. Example: 2026-07-31 23:59:59
    startDatestringrequired
    Start of the date range, in yyyy-MM-dd HH:mm:ss format. Read in the timezone given by timezone when one is supplied. Example: 2026-07-01 00:00:00
    regionstring
    Country code to filter bandwidth usage by region. When omitted, usage is not limited to a region. Example: us
    timezonestring
    IANA timezone name used to interpret startDate and endDate. When omitted, MrScraper's own default applies. Example: America/New_York
  • mrscraper_get_resultGet one scraping result by its id.Read-only

    Get Result

    Get one scraping result by its id. Returns data, the result record: createdAt, id, userId, scraperId, type (for example AI or Bulk-AI), url, status, error, tokenUsage, runtime, bandwidthUsage, the extracted data (its shape depends on the scraper's agent and on whether the run was single or bulk), and the path fields dataPath and htmlPath, which were null in testing; only Scrape-Markdown records, and one markdown run that also took a screenshot, carried file paths inside data, as data_path and html_path. For a bulk job, the record's data holds mergedData, urlDetails and a summary with totalUrls, successfulUrls, failedUrls, scrapedCount, totalTokenUsage and estimatedFinishAt. Scraper API records carry a curl field that replays the request and contains the live x-api-token value, so never repeat or store curl (AI, rerun and bulk records have curl null); read status, type, url, tokenUsage and data instead. MrScraper also saves rejected calls as Finished records: one with tokenUsage 0 whose data holds only an error body (an error message with a traceId, or a single detail field) is a rejected call, not a result. Use this to read a single result, and to poll a bulk job, using the bulkResultId returned by mrscraper_bulk_rerun_ai_scraper or mrscraper_bulk_rerun_manual_scraper, until its status is Finished, Failed or Cancelled (Running means it is still going). Use mrscraper_list_results to browse many results. Requires the result id, found with mrscraper_list_results or, for a bulk job, the bulkResultId in a bulk rerun response. An unknown id answers 403 and a malformed id 400.

    Inputs

    resultIdstringrequired
    ID of the result to fetch, a UUID. Take it from mrscraper_list_results, or use the bulkResultId from a bulk rerun response to poll a bulk job. Example: 497f6eca-6276-4993-bfeb-53cbbbba6f08
  • mrscraper_list_resultsList scraping results for the account, with sorting, text search, an optional date-range filter and page-based pagination.Read-only

    List Results

    List scraping results for the account, with sorting, text search, an optional date-range filter and page-based pagination. Returns data, an array of result records (createdAt, id, userId, scraperId, type, url, status, error, tokenUsage, runtime, bandwidthUsage, the extracted data, and the path fields dataPath, htmlPath, recordingPath and screenshotPath, which were null in testing; only Scrape-Markdown records, and one markdown run that also took a screenshot, carried file paths inside data, as data_path and html_path), plus meta with page, pageSize, total and totalPage. Scraper API records carry a curl field that replays the request and contains the live x-api-token value, so never repeat or store curl (AI, rerun and bulk records have curl null); read status, type, url, tokenUsage and data instead. MrScraper also saves rejected calls as Finished records: one with tokenUsage 0 whose data holds only an error body (an error message with a traceId, or a single detail field) is a rejected call, not a result. Use this to browse or find results and their ids; the date range needs both startAt and endAt (a single bound was ignored in testing) and dateRangeColumn had no effect. Use mrscraper_get_result to read one result by id, including the progress of a bulk job.

    Inputs

    pageintegerrequired
    Page number to return, starting at 1. The totalPage value in the response meta says how many pages exist. Example: 1
    pageSizeintegerrequired
    Number of results per page. MrScraper recommends no more than 100 per page to avoid timeouts. Example: 10
    sortFieldstringrequired
    Name of the result field to sort by, for example updatedAt.
    sortOrderstringrequired
    Sort direction: ASC for ascending or DESC for descending. Example: DESCone of ASCDESC
    dateRangeColumnstring
    Name of the result column that startAt and endAt filter on, for example createdAt. In testing it had no effect: the window applied the same way with createdAt, updatedAt, an unknown column name or no column.
    endAtstring
    End of the date range as an ISO 8601 timestamp, send it together with startAt, because a single bound was ignored in testing. Example: 2025-11-14T23:59:59.999Z
    searchstring
    Text to search for. Matching on url was observed; the vendor reference says it searches all result columns. When omitted, results are not filtered by text. Example: example.com
    startAtstring
    Start of the date range as an ISO 8601 timestamp, send it together with endAt, because a single bound was ignored in testing. Example: 2025-11-13T00:00:00.000Z
  • mrscraper_scrape_htmlFetch the raw HTML of one web page in HTML mode (the tool always sends html=true), with optional Chromium rendering, real-device routing, geo-targeted proxies and waiting for a CSS selector.Read-only

    Scrape HTML

    Fetch the raw HTML of one web page in HTML mode (the tool always sends html=true), with optional Chromium rendering, real-device routing, geo-targeted proxies and waiting for a CSS selector. Returns the page's unparsed markup as a single text string in the result field; the response is text, not JSON. Use this for raw markup to feed your own parser or to audit meta tags and page structure. Use mrscraper_scrape_markdown for clean text, mrscraper_scrape_json for structured fields from a prompt, mrscraper_get_screenshot for an image, and mrscraper_scrape_sitemap to discover URLs first. Each call consumes MrScraper plan tokens and is saved as a result record (this tool has no saveResult input). Scalekit ends every call after 10 seconds, whatever timeout says, and returns a timeout error; every html call finished inside that limit in testing, including calls with browser rendering. An invalid URL answers 400, and a target page that returns 404 comes back as an error.

    Inputs

    urlstringrequired
    The full URL of the page to fetch, including the protocol. Example: https://books.toscrape.com/
    blockResourcesboolean
    Set to true to block images, fonts and stylesheets from loading (the vendor reference says this speeds up the fetch and reduces bandwidth; not measured here). Leave unset for the server default.
    browserRenderingboolean
    Set to true to render the page in a Chromium browser so JavaScript-driven content is included. In testing it made a JavaScript-rendered page contain its content. Leave unset for the server default, which is documented as rendering off.
    geoCodestring
    Geographic code for the location of the proxy server, as a two-letter country code such as us, de or pt. Leave unset for the server default.
    proxyCountrystring
    Country of the proxy server, as a country code such as us. Leave unset for the server default.
    returnCookieboolean
    The vendor reference lists this switch for returning the page's session cookies. This tool returns only the page markup as text in result, and no cookies were seen in testing. Leave unset for the server default.
    superboolean
    The vendor reference describes super mode as routing the request through real devices to get past anti-bot protection; in testing it was accepted and cost the same 1 plan token as a default call on a simple site, but its effect on the returned markup was not measured. Try without it first and enable it only when standard routing does not return usable content. Leave unset to use standard routing.
    timeoutinteger
    Maximum number of seconds to wait for the page to fully load before the request times out. Increase it for slow or complex pages. Leave unset for the server default. Scalekit ends every call after 10 seconds, so a value above 10 adds no waiting time. Example: 8
    waitForSelectorstring
    CSS selector to wait for in the DOM before the page content is returned, useful for content that loads asynchronously after the initial page load. Example: div.product-list
    waitUntilstring
    When the browser considers navigation complete. One of domcontentloaded, load, networkidle0 or networkidle2; networkidle0 waits until all network activity stops. Leave unset for the server default.one of domcontentloadedloadnetworkidle0networkidle2
  • mrscraper_verify_api_tokenVerify the connected MrScraper API token and fetch the subscription account it belongs to.Read-only

    Verify API Token

    Verify the connected MrScraper API token and fetch the subscription account it belongs to. Returns the subscription account: its id, the owning user id (userId), plan details (subscriptionItem), status (stripeStatus), billing period (currentPeriodStart, currentPeriodEnd, endsAt, cancelAtPeriodEnd, isAutoRenew), token limit and usage (tokenLimit, tokenUsage), concurrency and rate limits (maxConcurrency, rateLimit, rateTtl), and a user object with the owner's profile (name, email, Google and Stripe ids, team). The user object is personal account data, so never repeat it in output and read only tokenLimit and tokenUsage for budget checks. The vendor docs example also shows a latestApiToken field that the live API did not return when checked; treat it as a secret if it ever appears. Use this to compare token usage against the token limit or as a quick auth check, since a 401 Unauthorized response means the token is missing or invalid. Use mrscraper_get_proxy_bandwidth for proxy usage and mrscraper_get_analytic_statuses for scrape status counts.

    Inputs

    This tool takes no inputs.

  • mrscraper_bulk_rerun_ai_scraperRun an existing AI scraper across many URLs in one asynchronous bulk job.Write

    Bulk Rerun AI Scraper

    Run an existing AI scraper across many URLs in one asynchronous bulk job. The vendor reference says reruns reuse cached results, which can reduce token usage and improve execution time; no saving was observed in testing. Returns data.bulkResultId, the id of the bulk job, with the message 'Bulk scraping is Running'; no extraction results come back in this response. Poll that id with mrscraper_get_result: status is Running while URLs are processed and becomes Finished (or Cancelled or Failed). The polled record's data holds mergedData (extraction output per page), urlDetails (status and error for each URL) and a summary of totalUrls, successfulUrls, failedUrls, scrapedCount, totalTokenUsage and estimatedFinishAt. Rely on status, not on mergedData or urlDetails, to know the job is done (the vendor reference says they fill in as URLs finish). estimatedFinishAt was null in every summary seen in testing. Finished means the job ended, not that every URL succeeded: read summary.failedUrls and each urlDetails status. Use this for many URLs and mrscraper_rerun_ai_scraper for a single URL. Stop a running job with mrscraper_cancel_bulk_result using the bulkResultId. Successful URLs consume plan tokens (10 per URL in the AI-scraper jobs seen in testing; URLs that failed added 0), so check tokenLimit and tokenUsage with mrscraper_verify_api_token before submitting a long list. Requires the scraperId of an AI scraper: read it from the scraperId field of the newest type-AI record in mrscraper_list_results, because mrscraper_create_ai_scraper normally times out in Scalekit before returning data.scraperId (that record appears only once creation finishes, 19 to 39 s after the call started). The vendor reference suggests a scraper built for item detail pages.

    Inputs

    scraperIdstringrequired
    ID (UUID) of the AI scraper to run on every URL: the scraperId field of its type-AI record in mrscraper_list_results (mrscraper_create_ai_scraper returns it as data.scraperId when it answers in time). Example: 4f6a04d6-7dc9-4676-bddf-edd19497b1dd
    urlsarrayrequired
    List of full URLs to scrape, each including the https:// prefix. Successful URLs consume tokens, so check your token balance before submitting a large list. Example: ["https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html", "https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html"]
  • mrscraper_bulk_rerun_manual_scraperRun an existing manual (workflow) scraper across many URLs in one asynchronous bulk job.Write

    Bulk Rerun Manual Scraper

    Run an existing manual (workflow) scraper across many URLs in one asynchronous bulk job. The vendor reference says reruns reuse cached results, which can reduce token usage and improve execution time; not observed in testing. Returns data.bulkResultId, the id of the bulk job, with the message 'Bulk scraping is Running'; no extraction results come back in this response. Poll that id with mrscraper_get_result: status is Running while URLs are processed and becomes Finished (or Cancelled or Failed). The polled record's data holds mergedData (extraction output per page), urlDetails (status and error for each URL) and a summary of totalUrls, successfulUrls, failedUrls, scrapedCount, totalTokenUsage and estimatedFinishAt. Rely on status, not on mergedData or urlDetails, to know the job is done (the vendor reference says they fill in as URLs finish). estimatedFinishAt was null in every summary seen in testing. Finished means the job ended, not that every URL succeeded: read summary.failedUrls and each urlDetails status. Use this for many URLs and mrscraper_rerun_manual_scraper for a single URL. Stop a running job with mrscraper_cancel_bulk_result using the bulkResultId. Successful URLs consume plan tokens (10 per URL in the AI-scraper jobs seen in testing; the cost of a manual-scraper URL was not observed), so check tokenLimit and tokenUsage with mrscraper_verify_api_token before submitting a long list. Requires the scraperId of a manual scraper that already exists in the MrScraper account, typically one built for item detail pages; this connector has no tool to create one. In testing an AI scraper's id was accepted and the job then ended Failed with zero tokens.

    Inputs

    scraperIdstringrequired
    ID (UUID) of the manual (workflow) scraper to run on every URL. It is typically a scraper built for individual item or detail pages. Example: 600e1d1c-4606-44b0-95e3-ce6c3789b380
    urlsarrayrequired
    List of full URLs to scrape, each including the https:// prefix. Successful URLs consume tokens, so check your token balance before submitting a large list. Example: ["https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html", "https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html"]
All 151 in AI