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": "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 Endpoints
Submit a Search
Run a real search query and get back structured results — web, news, images, and videos
POST
/
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": "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."
]
}How It Works
Search runs asynchronously, same pattern as scrape and crawl: submit a query, get ajobId back immediately, then poll GET /search/{jobId} until status is completed.
- Submit - Send your query, receive a
jobIdright away - Resolve - Spidra fetches real results, automatically retrying against alternate providers behind the scenes if one is temporarily blocked
- Poll - Check
GET /search/{jobId}untilstatus: "completed"
Automated requests to any web search provider can be intermittently blocked. Rather than surfacing that as a failure, Spidra retries automatically until it gets real results back — you don’t need to build retry logic yourself, and which provider ultimately answered is an internal implementation detail, not something you need to think about or configure.
Sources
By default a search only returnsweb results. Request additional sources 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 |
If a non-web source is temporarily unavailable, that source comes back as an empty array rather than failing the whole request.
Geo-Targeting
Passcountry to localize results to a specific region — a 2-letter country code, or global, eu, asia:
{
"query": "top restaurants",
"country": "fr"
}
Result Limit
Control how many results come back per source (1-20, default 10):{
"query": "electric cars",
"sources": ["web", "images"],
"limit": 20
}
Check Job Status
Poll for results
View Logs
See your search history
Authorizations
BearerAuthApiKeyAuth
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Was this page helpful?