Submit a Search

curl --request POST \
  --url https://api.spidra.io/api/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "best espresso machine 2026"
}
'

{
  "status": "completed",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "progress": {
    "message": "Search completed successfully",
    "progress": 1
  },
  "result": {
    "success": true,
    "data": {
      "web": [
        {
          "title": "Best Espresso Machines of 2026",
          "url": "https://example.com/best-espresso-machines-2026",
          "description": "Our picks for the best espresso machines this year, tested and compared.",
          "position": 1
        }
      ]
    },
    "stats": {
      "durationMs": 1980
    }
  },
  "error": null
}

{
  "status": "queued",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Search job has been queued. Poll /api/search/550e8400-e29b-41d4-a716-446655440000 to get the result."
}

{
  "status": "error",
  "message": "You have exceeded your monthly credit limit."
}

{
  "status": "error",
  "message": "Request validation failed. Fix the errors below and try again.",
  "errors": [
    "\"query\" is required and must be a non-empty string."
  ]
}

POST

curl --request POST \
  --url https://api.spidra.io/api/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "best espresso machine 2026"
}
'

{
  "status": "completed",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "progress": {
    "message": "Search completed successfully",
    "progress": 1
  },
  "result": {
    "success": true,
    "data": {
      "web": [
        {
          "title": "Best Espresso Machines of 2026",
          "url": "https://example.com/best-espresso-machines-2026",
          "description": "Our picks for the best espresso machines this year, tested and compared.",
          "position": 1
        }
      ]
    },
    "stats": {
      "durationMs": 1980
    }
  },
  "error": null
}

{
  "status": "queued",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Search job has been queued. Poll /api/search/550e8400-e29b-41d4-a716-446655440000 to get the result."
}

{
  "status": "error",
  "message": "You have exceeded your monthly credit limit."
}

{
  "status": "error",
  "message": "Request validation failed. Fix the errors below and try again.",
  "errors": [
    "\"query\" is required and must be a non-empty string."
  ]
}

Search runs a real query and returns structured results: titles, links, descriptions, thumbnails. Like scrape and crawl, it runs as an async job: you submit a query, get a jobId back, then poll GET /search/{jobId} until status is completed. Most searches resolve in a few seconds, and if you’d rather not poll at all, wait: true returns the result in this same call. Working with an AI assistant instead of writing code? The MCP server exposes this endpoint as the spidra_search tool. By default a search only returns web results. Request more with the sources array:

{
  "query": "best espresso machine 2026",
  "sources": ["web", "news", "images"]
}

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 pull requests

If a source is temporarily unavailable, that source comes back as an empty array rather than failing the whole request.

Geo-Targeting

Pass country to localize results to a specific region. This is usually a 2-letter country code, or global, eu, asia:

{
  "query": "top restaurants",
  "country": "fr"
}

Domain Filtering

Restrict web results to specific domains, or keep specific domains out. You can pass one or the other, but never both in the same request. With the following example, you can include only results from reddit.com:

{
  "query": "espresso machine reviews",
  "includeDomains": ["reddit.com"]
}

If you want to exclude results from certain domains, use excludeDomains instead:

{
  "query": "espresso machine reviews",
  "excludeDomains": ["pinterest.com"]
}

includeDomains, excludeDomains, and filetype only apply to web/news/images/videos. They’re not supported on research or developer, covered below.

Research and Developer Sources

The research source searches academic papers and returns authors and doi alongside the usual fields:

{
  "query": "transformer attention mechanisms",
  "sources": ["research"]
}

The developer source searches GitHub issues and pull requests. Write the query the way you’d type it into GitHub’s own search, qualifiers and all:

{
  "query": "memory leak is:issue repo:vercel/next.js",
  "sources": ["developer"]
}

PDF Search

Pass filetype: "pdf" to restrict web results to PDF files:

{
  "query": "annual report 2026",
  "filetype": "pdf"
}

Add scrapeOptions to fetch each PDF’s actual content as markdown in the same request. See Scrape Content From Results and Document URLs below.

HD Image Search With Size Filtering

For images results, add imagesize: or larger: straight into your query. It works the same way includeDomains/excludeDomains do above, just written inline instead of as a separate field. Here is an example using the imagesize: filter:

curl -X POST https://api.spidra.io/api/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "sunset imagesize:1920x1080",
    "sources": ["images"],
    "limit": 5
  }'

Here is another example using the larger: filter:

curl -X POST https://api.spidra.io/api/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "mountain wallpaper larger:1920x1080",
    "sources": ["images"],
    "limit": 8
  }'

Common resolutions:

imagesize:1920x1080: Full HD (1080p), exact
imagesize:2560x1440: QHD (1440p), exact
imagesize:3840x2160: 4K UHD, exact
larger:1920x1080: HD and above
larger:2560x1440: QHD and above

Scrape Content From Results

By default, Search returns metadata, but you can add scrapeOptions to also fetch each web result’s actual page content, in the same request:

{
  "query": "posthog before_send config",
  "scrapeOptions": {
    "formats": ["markdown"]
  }
}

Every web result actually gets scraped before the job reports completed. markdown lands directly on each result, the same call, no second request:

{
  "data": {
    "web": [
      {
        "title": "How to configure before_send",
        "url": "https://posthog.com/tutorials/...",
        "position": 1,
        "markdown": "# How to configure before_send\n\n..."
      }
    ]
  }
}

This makes a content-fetch search take as long as the slowest page it scrapes, not the usual 1-8 seconds.This is because real scraping isn’t instant, and Spidra would rather you wait once on one job than build your own polling loop around N separate scrape jobs.If you need results back fast and can fetch content separately afterward, leave scrapeOptions off and use POST /scrape on whichever URLs you actually want.

Content-fetch billing is separate from the search itself. Each scraped page costs the same as an ordinary scrape job.If you want AI extraction, a schema, HTML, or links instead of plain markdown, scrape the URL directly with POST /scrape.

Result Limit

Control how many results come back per source (1-20, default 10):

{
  "query": "electric cars",
  "sources": ["web", "images"],
  "limit": 20
}

Pagination

A completed search includes a nextPageTokens object with one opaque token per source that returned results. Pass it back as pageTokens on your next request to reliably continue where that source left off:

{
  "query": "espresso machine reviews",
  "pageTokens": {
    "web": "eyJwYWdlIjoyfQ"
  }
}

That token is whatever came back in the previous response’s data.nextPageTokens.web, not something you construct yourself:

{
  "data": {
    "web": [ /* ... */ ],
    "nextPageTokens": {
      "web": "eyJwYWdlIjoyfQ"
    }
  }
}

You can also pass a plain page number instead:

{
  "query": "espresso machine reviews",
  "page": 2
}

pageTokens is more reliable than a plain page number since it continues from the exact result set your last response returned. A source without a token, or with no more pages left, is simply absent from nextPageTokens.Tokens are sealed values that only Spidra can read. Pass them back exactly as you received them. A token that has been changed, or that is too old to resume, is not an error: that source just runs as a fresh search.position also behaves differently between the two. With pageTokens, positions continue across pages (11, 12, 13 on page 2). With a plain page number, each page numbers its results from 1.

Time Range

Pass timeRange to restrict results to a recency window: hour, day, week, month, or year. This is especially useful for news, where older results usually matter less:

{
  "query": "product launch",
  "sources": ["news"],
  "timeRange": "week"
}

Support can vary by source and query. A window that can’t be honored is simply ignored rather than erroring, so you may occasionally see slightly wider results than requested.

Get the Result Without Polling

For a plain search without scrapeOptions, pass wait: true to hold the request open and get the result back in this same call:

{
  "query": "best espresso machine 2026",
  "wait": true
}

When it works, the response comes back with status: "completed" and the real result already attached, the same shape GET /search/{jobId} returns once a polled job finishes:

{
  "status": "completed",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "progress": { "message": "Search completed successfully", "progress": 1 },
  "result": {
    "success": true,
    "data": { "web": [ /* ... */ ] },
    "stats": { "durationMs": 1980 }
  },
  "error": null
}

If the search doesn’t finish within the wait window (about 20 seconds), the response falls back to the normal 202 and jobId you’d get without wait, and you poll GET /search/{jobId} from there. wait is ignored whenever scrapeOptions is set, since that case can legitimately take much longer than any request should stay open.

Extras

When available for the query, web results come with an extras object alongside them: related searches, a trending news carousel, or a direct answer box such as a currency conversion.

{
  "data": {
    "web": [ /* ... */ ],
    "extras": {
      "answerBox": { "type": "currency", "value": "17.43 Euro" },
      "relatedSearches": ["20 usd to gbp", "usd to eur exchange rate today"]
    }
  }
}

extras is only present when Spidra actually found one of these for that specific query. It’s never guaranteed, and never present for news/images/videos.

Check Job Status

Poll for results

View Logs

See your search history

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

query

string

required

The search query

Maximum string length: 2000

sources

enum<string>[]

Which result types to fetch. research returns academic papers, developer returns GitHub issues and PRs.

Available options:

web,

news,

images,

videos,

research,

developer

limit

integer

default:10

Results per source

Required range: 1 <= x <= 20

page

integer

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.

Required range: x >= 1

pageTokens

object

One opaque token per source, taken from a prior response's nextPageTokens, for reliably continuing to that source's next page.

Show child attributes

timeRange

enum<string>

Restricts results to a recency window. Support can vary by source and query, and a window that can't be honored is simply ignored rather than erroring.

Available options:

hour,

day,

week,

month,

year

country

string

2-letter country code, or 'global', 'eu', 'asia'

includeDomains

string[]

Only return web results from these domains (site: operator). Mutually exclusive with excludeDomains -- sending both is a validation error.

Maximum array length: 20

excludeDomains

string[]

Exclude web results from these domains (-site: operator). Mutually exclusive with includeDomains -- sending both is a validation error.

Maximum array length: 20

filetype

enum<string>

Restricts results to PDF files. Doesn't apply to research/developer sources.

Available options:

pdf

wait

boolean

default:false

Hold the request open and respond with the real result directly, instead of always returning a queued job to poll. Ignored when scrapeOptions is set. Falls back to the normal queued response if the search doesn't finish within the wait window (about 20 seconds).

scrapeOptions

object

Opt-in: also fetch each web result's actual page content before the job reports completed. The markdown lands directly on each enriched result, with no second job id to poll. A content-fetch search takes as long as the slowest scraped page (real scraping isn't instant), not the usual 1-8s.

Show child attributes

Response

Job completed within the wait window (only possible when wait: true was sent and scrapeOptions was not set)

status

enum<string>

Available options:

completed,

failed

jobId

string

progress

object

Show child attributes

result

object | null

Present only when status is 'completed'

Show child attributes

error

string | null

Using the API

Scrape Endpoints

Search Endpoints

Crawl Endpoints

Account

Submit a Search

Geo-Targeting

Domain Filtering

Research and Developer Sources

PDF Search

HD Image Search With Size Filtering

Scrape Content From Results

Result Limit

Time Range

Get the Result Without Polling

Extras

Check Job Status

View Logs

Authorizations

Body

Response

​Geo-Targeting

​Domain Filtering

​Research and Developer Sources

​PDF Search

​HD Image Search With Size Filtering

​Scrape Content From Results

​Result Limit

​Pagination

​Time Range

​Get the Result Without Polling

​Extras

Check Job Status

View Logs

Authorizations

Body

Response

Geo-Targeting

Domain Filtering

Research and Developer Sources

PDF Search

HD Image Search With Size Filtering

Scrape Content From Results

Result Limit

Pagination

Time Range

Get the Result Without Polling

Extras