Start an async crawl of one site (1 credit per page read; `limit` credits reserved up front, the rest refunded)

From url and (unless sitemap: skip) the site's sitemaps, same host (optionally subdomains), up to limit pages and max_depth link hops, filtered by include_paths / exclude_paths (regular expressions matched against the URL path). Breadth first, or best first with query (pages whose URL and link text match it are read first). Each host's robots.txt is honoured (RFC 9309: rules, Crawl-delay; a robots.txt that answers 5xx stops the crawl at the start page). URLs are canonicalised (fragments and tracking parameters dropped, www., trailing slashes and redirects folded) so each page is read once. Each page comes back as Markdown (or text) with its metadata. A crawl runs for at most 30 minutes and returns up to 16 MB of pages; result.stats.stopped says why it ended.

Returns 202 with a task; poll GET /v1/crawl/{id} or wait for the signed crawl.completed webhook. Pages read cost 1 credit each (0.5 from cache); a crawl that read nothing fails (no_pages) and is refunded. At most 20 crawls per account may be queued or running at once (429); a crawl interrupted by a deploy restarts from the beginning.

post/v1/crawl

Request

  • Base URL: https://api.serpkite.com
  • URL: https://api.serpkite.com/v1/crawl
  • Auth: HTTP bearer

Request body

urlstring uri required

Start page (always read: path filters and robots.txt apply to the pages found from it)

limitinteger

Maximum pages read (and credits reserved)

max_depthinteger

Link hops from url (sitemap pages count as 1 hop; 0 reads only url)

include_pathsstring[]

Regular expressions matched against the URL path; follow only paths matching one

exclude_pathsstring[]

Regular expressions matched against the URL path; never follow paths matching one

include_subdomainsboolean
sitemap'include' | 'only' | 'skip'

include also seeds the crawl with the site's sitemap URLs (after the start page's links), only reads the start page and sitemap URLs without following links, skip follows links only

querystring

Read the pages most relevant to these words first (best-first crawl)

ignore_query_parametersboolean

Treat URLs that differ only in their query string as one page

format'markdown' | 'text'
include_linksboolean

Return each page's outbound links

max_tokensinteger

Trim each page to this many tokens

max_ageinteger

Accept cached pages up to this many seconds old (0.5 credit each)

webhook_urlstring uri

Receives the signed crawl.completed event. Defaults to the account webhook

Response

Queued. Poll poll_url or wait for the webhook

idstring uuid required
kind'crawl' required
status'queued' | 'running' | 'completed' | 'failed' | 'canceled' required
created_atstring date-time required
poll_urlstring required
credits_reservednumber required
webhook_urlstring nullable

Changes

No recorded changes to this operation across all 1 revision of this API.