Skip to main content

API Reference

Base URL​

All API requests should be made to:

https://spideriq.ai

Authentication​

All endpoints require Bearer token authentication. See Authentication for details.

Authorization: Bearer <client_id>:<api_key>:<api_secret>

API Endpoints​

Job Management​

Submit and manage scraping jobs.

📨

Submit Job

POST /api/v1/jobs/submit

🌍

SpiderSite Job

POST /api/v1/jobs/spiderSite/submit

🗺️

SpiderMaps Job

POST /api/v1/jobs/spiderMaps/submit

📧

SpiderVerify Job

POST /api/v1/jobs/spiderVerify/submit

👤

SpiderPeople Job

POST /api/v1/jobs/spiderPeople/submit

ℹ️

Get Status

GET /api/v1/jobs/{id}/status

📃

Get Results

GET /api/v1/jobs/{id}/results

📋

List Jobs

GET /api/v1/jobs/list

❌

Cancel Job

DELETE /api/v1/jobs/{id}

SpiderMaps Campaigns (v2.14.0)​

Orchestrate multi-location Google Maps scraping with campaigns.

🎯

Create Campaign

POST /api/v1/jobs/spiderMaps/campaigns/submit

➡️

Get Next Location

POST /api/v1/jobs/spiderMaps/campaigns/{id}/next

📈

Campaign Status

GET /api/v1/jobs/spiderMaps/campaigns/{id}/status

⏸️

Stop Campaign

POST /api/v1/jobs/spiderMaps/campaigns/{id}/stop

▶️

Continue Campaign

POST /api/v1/jobs/spiderMaps/campaigns/{id}/continue

📋

List Campaigns

GET /api/v1/jobs/spiderMaps/campaigns

Locations (v2.14.0)​

Query the global location database with 44,691 cities across 240 countries.

📍

List Locations

GET /api/v1/locations

📉

Location Stats

GET /api/v1/locations/stats

🌍

List Countries

GET /api/v1/locations/countries

SpiderSearch (v2.30.0)​

Search across all your indexed job results with full-text search, faceted filtering, and geo-radius queries.

🏢

Search Businesses

GET /api/v1/search/businesses

👥

Search Leads

GET /api/v1/search/leads

🔎

Search All

GET /api/v1/search/all

⌨️

Autocomplete

GET /api/v1/search/autocomplete

📉

Aggregations

GET /api/v1/search/aggregations

System​

Monitor system health and queue statistics.

💓

Health Check

GET /api/v1/system/health

📈

Queue Stats

GET /api/v1/system/queue-stats

🖥️

System Info

GET /api/v1/system/info

SpiderBrowser (Admin)​

Manage browser profiles, sessions, and cookie exports.

👥

Create Profile

POST /api/v1/admin/browser/profiles

📋

List Profiles

GET /api/v1/admin/browser/profiles

▶️

Start Browser

POST /api/v1/admin/browser/profiles/{id}/start

⏹️

Stop Browser

POST /api/v1/admin/browser/profiles/{id}/stop

🍪

Export Cookies

POST /api/v1/admin/browser/profiles/{id}/cookies/export

📊

Browser Stats

GET /api/v1/admin/browser/stats

YAML/MD Format Support (v2.60.0)​

SpiderIQ supports YAML and Markdown response formats for AI agent integration, providing 40-50% token savings.

GET Endpoints: Format Parameter​

Add ?format=yaml or ?format=md to any GET endpoint:

# YAML format (token-efficient for AI agents)
curl "https://spideriq.ai/api/v1/jobs/{job_id}/status?format=yaml" \
  -H "Authorization: Bearer $TOKEN"

# Markdown format (human-readable)
curl "https://spideriq.ai/api/v1/jobs/{job_id}/results?format=md" \
  -H "Authorization: Bearer $TOKEN"

YAML Response Example:

job_id: 974ceeda-84fe-4634-bdcd-adc895c6bc75
type: spiderSite
status: completed
priority: 5
created_at: '2026-03-13T10:30:00'
processing_time_seconds: 19.77
pages_crawled: 8

Markdown Response Example:

## Job: 974ceeda-84fe-4634-bdcd-adc895c6bc75
**Type**: spiderSite | **Status**: completed | **Priority**: 5
**Processing Time**: 19.77s
**Pages Crawled**: 8

POST/PATCH Endpoints: YAML Input​

Submit payloads in YAML format using Content-Type: text/yaml:

# SpiderSite job with YAML payload
curl -X POST "https://spideriq.ai/api/v1/jobs/spiderSite/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/yaml" \
  -d '
url: https://example.com
max_pages: 10
extract_team: true
compendium:
  enabled: true
  cleanup_level: fit
'

# SpiderMaps job with YAML payload
curl -X POST "https://spideriq.ai/api/v1/jobs/spiderMaps/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/yaml" \
  -d '
search_query: coffee shops near me
max_results: 20
extract_reviews: true
'

Supported Content Types​

Content-TypeAccepted
text/yaml✅
application/yaml✅
application/x-yaml✅
application/json✅ (default)

Token Efficiency​

FormatTokens (typical)Savings
JSON~200baseline
YAML~12040%
Markdown~10050%

Response Format​

Success Response​

All successful responses follow a consistent structure:

{
  "success": true,
  "job_id": "uuid",
  "type": "spiderSite" | "spiderMaps" | "spiderVerify" | "spiderPeople",
  "status": "completed",
  "data": {
    // Flat structure with results
  }
}

Error Response​

Error responses include detailed error information:

{
  "detail": "Error message describing what went wrong"
}

Status Codes​

CodeMeaningDescription
200OKRequest successful, results available
201CreatedResource created successfully
202AcceptedRequest accepted, processing (poll for results)
400Bad RequestInvalid request format or parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenClient account inactive
404Not FoundResource not found
410GoneJob failed or was cancelled
422Unprocessable EntityValidation error (internal bug)
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer error
503Service UnavailableQueue service unavailable

Rate Limiting​

  • Limit: 100 requests per minute per client
  • Burst: 20 requests allowed in burst
  • Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

When rate limited, you'll receive a 429 response with a Retry-After header.

Pagination​

List endpoints support pagination:

GET /api/v1/jobs/list?page=1&page_size=50

Parameters:

  • page - Page number (default: 1)
  • page_size - Items per page (default: 50, max: 100)

Response:

{
  "total": 1234,
  "page": 1,
  "page_size": 50,
  "jobs": [...]
}

Filtering​

List jobs by status or type:

GET /api/v1/jobs/list?status_filter=completed&type_filter=spiderSite

Versioning​

Current API version: v1

The version is included in the URL path: /api/v1/*

OpenAPI Specification​

Download the complete OpenAPI spec:

📝

OpenAPI JSON

View or download the OpenAPI 3.0 specification

SDKs and Libraries​

Currently, SpiderIQ does not provide official SDKs. Use standard HTTP libraries:

  • Python: requests, httpx
  • JavaScript: fetch, axios
  • PHP: curl, Guzzle
  • Go: net/http
  • Ruby: faraday, httparty

Support​

Need help? Contact us:

🛟

Get Support

Email our support team