Search

Search runs a query and returns the results as structured data: titles, links, descriptions and positions, plus fields specific to each source. Nothing is summarised or rewritten. It answers “which pages exist for this query?”; Scrape answers “what’s on this page?”. Add scrapeOptions to get both in one request.

Quick example

curl -X POST https://api.spidra.io/api/search \
  -H "Authorization: Bearer $SPIDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "best espresso machine", "sources": ["web"], "limit": 3, "wait": true }'

const search = await spidra.search({ query: "best espresso machine", sources: ["web"], limit: 3 });

for (const r of search.data.web) console.log(r.position, r.title);
// 1 The 16 Best Espresso Machines of 2026, Tested & Reviewed
// 2 Best Espresso Machines 2026 | Tested - Forbes Vetted

search = client.search("best espresso machine", sources=["web"], limit=3)

for r in search.data.web:
    print(r.position, r.title)
# 1 The 16 Best Espresso Machines of 2026, Tested & Reviewed
# 2 Best Espresso Machines 2026 | Tested - Forbes Vetted

With "wait": true, a search that finishes within 20 seconds answers in the same request (shortened to two results):

{
  "status": "completed",
  "jobId": "...",
  "result": {
    "success": true,
    "data": {
      "web": [
        {
          "title": "The 16 Best Espresso Machines of 2026, Tested & Reviewed",
          "url": "https://www.seriouseats.com/best-espresso-machines-5185482",
          "description": "We tested 41 home espresso machines to find which 16 pulled the best shots, steamed latte art-worthy microfoam, and were easy to use. We have top picks at all prices.",
          "position": 1
        },
        {
          "title": "Best Espresso Machines 2026 | Tested - Forbes Vetted",
          "url": "https://www.forbes.com/sites/forbes-personal-shopper/article/best-espresso-machine/",
          "description": "For devotees of handcrafted café beverages, investing in an espresso machine can save both time and money...",
          "position": 2
        }
      ],
      "nextPageTokens": { "web": "v1.WsrkJb5NyTSUa0o5..." }
    }
  }
}

Without wait, or when it takes longer, you get 202 with a jobId to poll at GET /search/{jobId}. The SDKs handle both.

Sources

Pick one or more in sources. Each runs on its own, so one empty source doesn’t affect the others.

Source	Results	Fields beyond `title`, `url`, `description`, `position`
`web` (default)	Web pages
`news`	News articles	`date` (as the source gives it, such as “3 days ago”), and often `source` and `thumbnailUrl`
`images`	Images	`imageUrl`, `thumbnailUrl`; `url` is the page the image is on
`videos`	Videos	`duration`, sometimes `date` and `thumbnailUrl`
`research`	Papers from arXiv, PubMed, bioRxiv and medRxiv	`authors`, `date`, `source`, and `doi` when the paper has one
`developer`	GitHub issues and pull requests, and repositories or users with `developerTypes`	`authors`, `date`, `source: "GitHub"`

Real results from a search for vector database across three sources:

{
  "news": [{ "title": "VCs are obsessed with vector databases. Here are seven AI startups in the space that have raised millions from investors.", "url": "https://www.businessinsider.com/seven-vector-database-startups-poised-to-win-ai-revolution-2024-4" }],
  "research": [{ "title": "BioVDB: biological vector database for high-throughput gene expression meta-analysis.", "url": "https://doi.org/10.3389/frai.2024.1366273" }],
  "developer": [{ "title": "PR: feat(vector-db): add Qdrant vector database support (#273)", "url": "https://github.com/arakoodev/EdgeChains/pull/706" }]
}

Not every field is on every result. Build for title, url and description, and treat the rest as extras. For developer, GitHub search qualifiers work in the query: memory leak is:issue repo:vercel/next.js. developerTypes picks what the developer source returns: any of "issues" (issues and pull requests, the default), "repositories" and "users", in the order you want them. Each type returns up to limit results into the same developer list, so ["repositories", "issues"] with a limit of 10 can return 20. Titles start with Repo:, User:, Issue: or PR: so you can tell them apart, and a repository’s description starts with its language and star count.

Options

Option	What it does
`query` (required)	What to search for.
`sources`	One or more of the six sources. Default `["web"]`.
`limit`	1 to 20 results per source. Default 10.
`country`	A two-letter code, or `global`, `eu`, `asia`. Shapes results toward that country.
`timeRange`	`hour`, `day`, `week`, `month` or `year`. Favors newer results; not a hard cutoff.
`includeDomains` / `excludeDomains`	Only, or never, these sites (one or the other). Applies to web, news, images and videos, and is enforced.
`filetype`	`"pdf"` returns only PDF links from the web. Works best on topical queries.
`developerTypes`	For the `developer` source: `"issues"`, `"repositories"` and `"users"`, one or more. Default `["issues"]`.
`scrapeOptions`	Read the top results’ pages too (below).
`wait`	Answer in the same request when it finishes within 20 seconds. Ignored with `scrapeOptions`.
`pageTokens`	Get the next page (below).

Get each page’s content

Add scrapeOptions and the top results come back with their page as clean Markdown:

{
  "query": "how to redact data in posthog",
  "sources": ["web"],
  "limit": 2,
  "scrapeOptions": { "formats": ["markdown"], "maxResults": 1 }
}

{
  "title": "How to redact event data before it is sent to PostHog - PostHog",
  "url": "https://posthog.com/tutorials/web-redact-properties",
  "description": "PostHog will use the client IP address found during an event capture request if an $ip isn't passed...",
  "position": 1,
  "markdown": "# How to redact event data before it is sent to PostHog\n\n..."
}

Only the first maxResults results get markdown; the second result above has none.
The search waits until every page is read, so expect tens of seconds. This one took 41.
A page that can’t be read is left without markdown; the rest are unaffected.
Results from popular sites also get structuredData.
For a prompt, a schema or a screenshot, scrape the URL instead.

More results

A finished search has nextPageTokens, one per source that has more. Send it back as pageTokens with the same query to get the next page:

{ "query": "best espresso machine", "sources": ["web"], "limit": 10, "pageTokens": { "web": "v1.WsrkJb5NyTSUa0o5..." } }

Positions carry on from the last page. Each page is charged like a new search. Occasionally a result from one page reappears on the next, so de-duplicate by URL when you collect many pages.

Cost

1 credit per 10 results, per source, rounded up. A source with no results costs nothing. Page content adds 1 credit per page read.

Search	Credits
Web, 10 results	1
Web, 20 results	2
Web, news, images and videos, 5 each	4
Web, 5 results, content for all 5	6

In the dashboard

Open Search in the sidebar. Type a query, pick sources, a country, results per source, a time range, domains, PDF results only, and Scrape content from search results. Results are grouped by source in tabs, with a readable list, a JSON view, copy, download (images download as a ZIP), and Load more results for the next page. Scrape page on a result opens it in Scrape.

Search results in tabs for Web, News, Images and Videos

Good to know

country and timeRange shape results; they don’t strictly filter them.
Related searches and quick answers (data.extras) appear on some web searches. Don’t rely on them.
A search with no results costs nothing, so trying a narrower query is free when it finds nothing.

Scrape

Extract data from a result’s page.

Templates

Google rank tracking and news, ready-made.

Monitors

Get told when new results appear.

API reference

Every field and response.

Get started

Tools

Ready-made data

Getting the data you want

Popular sites

Dashboard

Account and billing

Quick example

Sources

Options

Get each page’s content

More results

Cost

In the dashboard

Good to know

Next

Scrape

Templates

Monitors

API reference

​Quick example

​Sources

​Options

​Get each page’s content

​More results

​Cost

​In the dashboard

​Good to know

​Next

Scrape

Templates

Monitors

API reference

Quick example

Sources

Options

Get each page’s content

More results

Cost

In the dashboard

Good to know

Next