Spidra Node SDK
This is the official Node.js SDK for Spidra. It searches the web, scrapes pages, runs browser actions, batch-processes URLs, and crawls entire sites.
Every result comes back as structured data, clean markdown ready to feed into an LLM pipeline, your own systems and research, or just store directly.
Installation
To install the Spidra Node SDK, you can use npm:
npm install spidra
Get your API key at app.spidra.io under API Keys.
Quick start
Create a client with your API key, then call whichever method fits what you need. Here's a scrape:
import { SpidraClient } from "spidra";
const spidra = new SpidraClient({ apiKey: "spd_YOUR_API_KEY" });
const result = await spidra.scrape({
urls: [{ url: "https://news.ycombinator.com" }],
prompt: "List the top 5 stories with title, points, and comment count",
output: "json",
});
console.log(result.content);
Table of contents
Searching
Search runs a real query and returns structured results: titles, links, descriptions, thumbnails. It's the same data you'd get scraping a search engine yourself, minus the scraping. Unlike scrape/batch/crawl, a plain search usually resolves in a few seconds, often within the single search() call below with no polling at all.
const result = await spidra.search({
query: "best espresso machine 2026",
sources: ["web", "news"],
});
for (const hit of result.data.web ?? []) {
console.log(hit.title, hit.url);
}
By default only web results come back. Request more with sources:
| Source | Description |
|---|
web | Standard web results (default) |
news | News articles |
images | Image results |
videos | Video results |
research | Academic papers from arXiv, PubMed, bioRxiv, and medRxiv |
developer | GitHub issues and PRs. |
Each source is independent. If one comes back empty or is temporarily unavailable, the others are unaffected.
All search parameters:
| Parameter | Type | Description |
|---|
query | string | Required. What to search for. |
sources | ("web" | "news" | "images" | "videos" | "research" | "developer")[] | Which result types to request. Defaults to ["web"]. |
limit | number | Results per source, 1–20. Defaults to 10. |
page | number | 1-indexed page number. Prefer pageTokens once you have one, it's a more reliable way to continue to the next page than a bare page number. |
pageTokens | Partial<Record<Source, string>> | Opaque per-source token from a prior response's nextPageTokens, for reliably continuing to that source's next page. |
timeRange | "hour" | "day" | "week" | "month" | "year" | Restricts results to a recency window. Support can vary by source and query, and a window that can't be honored is simply ignored. |
country | string | Two-letter country code, or "global" / "eu" / "asia", for localized results. |
includeDomains | string[] | Only return web results from these domains. Mutually exclusive with excludeDomains. Doesn't apply to research/developer. |
excludeDomains | string[] | Keep web results from these domains out. Mutually exclusive with includeDomains. Doesn't apply to research/developer. |
filetype | "pdf" | Restricts results to PDFs. |
scrapeOptions | { formats, maxResults? } | Opt-in, also scrapes each web result's page content (see below). |
Research and developer sources
research searches academic papers, and returns authors and doi alongside the usual fields:
const result = await spidra.search({
query: "transformer attention mechanisms",
sources: ["research"],
});
for (const paper of result.data.research ?? []) {
console.log(paper.title, paper.authors, paper.doi);
}
developer searches GitHub issues and PRs. Write the query the way you'd type it into GitHub's own search, qualifiers and all:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
