> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spidra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Search the web, news, images, videos, research papers and GitHub, and get structured results back, optionally with each page's content. 1 credit per 10 results.

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](https://docs.spidra.io/scrape.md) answers "what's on this page?". Add `scrapeOptions` to get both in one request.

## Quick example

```bash curl theme={null}
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 }'
```

```typescript Node.js theme={null}
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
```

```python Python theme={null}
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):

```json theme={null}
{
  "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}](https://docs.spidra.io/api-reference/search/search-status.md). 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 | `authors`, `date`, `source: "GitHub"` |

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

```json theme={null}
{
  "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`.

## 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. |
| `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:

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

```json theme={null}
{
  "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 [supported sites](https://docs.spidra.io/sites/overview.md) also get `structuredData`.
* For a prompt, a schema or a screenshot, [scrape](https://docs.spidra.io/scrape.md) 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:

```json theme={null}
{ "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](https://docs.spidra.io/scrape.md).

![Search results in tabs for Web, News, Images and Videos](https://mintcdn.com/spidra/tYwOCi6kwOwEq7NW/images/search-results-tabs.webp?fit=max\&auto=format\&n=tYwOCi6kwOwEq7NW\&q=85\&s=c8c7e796d23a21a298772df68a6f288e)

## 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.

## Next

> **[Scrape](https://docs.spidra.io/scrape.md)**
>
> Extract data from a result's page.

> **[Templates](https://docs.spidra.io/templates.md)**
>
> Google rank tracking and news, ready-made.

> **[Monitors](https://docs.spidra.io/monitors.md)**
>
> Get told when new results appear.

> **[API reference](https://docs.spidra.io/api-reference/search/search.md)**
>
> Every field and response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.