☰ Core / run()
Docs / Core
run()
run<T = unknown>(projectKey, endpoint, params?, opts?): Promise<T> issues a single scraper call. The request URL is {baseURL}/v1/{projectKey}/{endpoint}[/{pathRest}]. You don't pick an HTTP method — the SDK auto-detects the endpoint's verb (a wrong first guess is flipped once on 405 and the learned verb is memoized per endpoint). GET params become the query string, POST params the JSON body. Path params like :slug are plain fields in params — no URL templating needed.
// No method to pick — auto-detected (and memoized) per endpoint.const spot = await client.run("finance:goldprice", "spot", {}); // Endpoints with path params (e.g. article/:slug)? Path params are// just regular fields in params — all of these are equivalent:await client.run("finance:goldprice", "article", { slug: "gold-hits-ath" });await client.run("finance:goldprice", "article/:slug", { slug: "gold-hits-ath" }); // Explicit method still works and skips auto-detection:const data = await client.run( "social:instagram", "profile", { username: "instagram" }, { method: "GET" });// No method to pick — auto-detected (and memoized) per endpoint.const spot = await client.run("finance:goldprice", "spot", {}); // Endpoints with path params (e.g. article/:slug)? Path params are// just regular fields in params — all of these are equivalent:await client.run("finance:goldprice", "article", { slug: "gold-hits-ath" });await client.run("finance:goldprice", "article/:slug", { slug: "gold-hits-ath" }); // Explicit method still works and skips auto-detection:const data = await client.run( "social:instagram", "profile", { username: "instagram" }, { method: "GET" });| RunOpts | Type | Purpose |
|---|---|---|
| method | "GET" | "POST" | Optional override; omitted = auto-detected and memoized per endpoint. |
| signal | AbortSignal | External abort signal, composed with the timeout. |
| timeoutMs | number | Per-call override of the client timeout. |
| idempotencyKey | string | Required to make a POST retry-eligible; reused across attempts. |
| headers | Record<string, string> | Per-request header overrides. |
| pathRest | string | Appended to the URL after the endpoint segment. |
| ttl | number | Max age in seconds you accept for a cached result. Paid plans only. |
method
Type: "GET" | "POST"
Purpose: Optional override; omitted = auto-detected and memoized per endpoint.
signal
Type: AbortSignal
Purpose: External abort signal, composed with the timeout.
timeoutMs
Type: number
Purpose: Per-call override of the client timeout.
idempotencyKey
Type: string
Purpose: Required to make a POST retry-eligible; reused across attempts.
headers
Type: Record<string, string>
Purpose: Per-request header overrides.
pathRest
Type: string
Purpose: Appended to the URL after the endpoint segment.
ttl
Type: number
Purpose: Max age in seconds you accept for a cached result. Paid plans only.
ttl asks for data fresher than the endpoint normally caches. It is a max-age, not a stored lifetime: a short ttl never shortens the cached entry for other callers, it only decides whether the existing entry is fresh enough for your call. The server clamps it to your plan's floor and the endpoint's own cache lifetime, then reports what it honoured in the X-Cache-Max-Age response header. ttl: 0 always fetches fresh. Plans without a floor configured get a ZpiPlanGateError instead.
Docs menu