Quickstart

Get Your API Credentials

Before you begin, you'll need API credentials. Contact us to register a client:

✉️

Request API Access

Email admin@spideriq.ai to get your credentials

You'll receive:

• Client ID: cli_abc123...
• API Key: sk_def456...
• API Secret: secret_ghi789...

warning

Store your credentials securely - they are shown only once!

Make Your First Request

1. Check API Health

First, verify the API is accessible:

cURL

curl https://spideriq.ai/api/v1/system/health

Python

import requests

response = requests.get("https://spideriq.ai/api/v1/system/health")
print(response.json())

JavaScript

const response = await fetch('https://spideriq.ai/api/v1/system/health');
const data = await response.json();
console.log(data);

2. Submit a Scraping Job

Let's scrape a website:

cURL

curl -X POST https://spideriq.ai/api/v1/jobs/spiderSite/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>" \
  -d '{
    "payload": {
      "url": "https://example.com"
    },
    "priority": 5
  }'

Python

import requests

headers = {
    "Authorization": "Bearer <your_token>"
}

data = {
    "payload": {
        "url": "https://example.com"
    },
    "priority": 5
}

response = requests.post(
    "https://spideriq.ai/api/v1/jobs/spiderSite/submit",
    headers=headers,
    json=data
)

job_id = response.json()["job_id"]
print(f"Job submitted: {job_id}")

JavaScript

const headers = {
  'Authorization': 'Bearer <your_token>',
  'Content-Type': 'application/json'
};

const data = {
  payload: {
    url: 'https://example.com'
  },
  priority: 5
};

const response = await fetch(
  'https://spideriq.ai/api/v1/jobs/spiderSite/submit',
  {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  }
);

const result = await response.json();
console.log(`Job submitted: ${result.job_id}`);

Response:

{
  "job_id": "974ceeda-84fe-4634-bdcd-adc895c6bc75",
  "type": "spiderSite",
  "status": "queued",
  "created_at": "2025-10-27T10:30:00Z",
  "from_cache": false,
  "message": "Job submitted successfully and queued for processing"
}

3. Poll for Results

Check if your job is complete:

cURL

curl https://spideriq.ai/api/v1/jobs/<job_id>/results \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>"

Python

import requests
import time

job_id = "974ceeda-84fe-4634-bdcd-adc895c6bc75"
headers = {"Authorization": "Bearer <your_token>"}

while True:
    response = requests.get(
        f"https://spideriq.ai/api/v1/jobs/{job_id}/results",
        headers=headers
    )

    if response.status_code == 200:
        # Job completed!
        data = response.json()["data"]
        print(f"Emails: {data['emails']}")
        print(f"LinkedIn: {data['linkedin']}")
        break
    elif response.status_code == 202:
        # Still processing
        print("Waiting for job to complete...")
        time.sleep(5)
    else:
        # Error
        print(f"Error: {response.json()}")
        break

JavaScript

const pollResults = async (jobId) => {
  const headers = {
    'Authorization': 'Bearer <your_token>'
  };

  while (true) {
    const response = await fetch(
      `https://spideriq.ai/api/v1/jobs/${jobId}/results`,
      { headers }
    );

    if (response.status === 200) {
      // Job completed!
      const result = await response.json();
      console.log('Emails:', result.data.emails);
      console.log('LinkedIn:', result.data.linkedin);
      break;
    } else if (response.status === 202) {
      // Still processing
      console.log('Waiting for job to complete...');
      await new Promise(resolve => setTimeout(resolve, 5000));
    } else {
      // Error
      const error = await response.json();
      console.error('Error:', error);
      break;
    }
  }
};

Status Codes:

• 200 OK - Job completed, results available
• 202 Accepted - Job queued/processing, poll again
• 410 Gone - Job failed or was cancelled

Understanding the Response

When your job completes (200 OK), you'll get a flat structure response:

{
  "success": true,
  "job_id": "974ceeda-84fe-4634-bdcd-adc895c6bc75",
  "type": "spiderSite",
  "status": "completed",
  "processing_time_seconds": 19.77,
  "worker_id": "spider-site-main-1",
  "completed_at": "2025-10-27T11:42:20Z",
  "data": {
    "url": "https://example.com",
    "pages_crawled": 10,
    "emails": ["contact@example.com"],
    "phones": ["+1-555-0123"],
    "linkedin": "https://linkedin.com/company/example",
    "twitter": null,
    "facebook": "https://facebook.com/example",
    // ... all 14 social platforms at top level
    "markdown_compendium": "# Content summary...",
    "metadata": {
      "browser_rendering_available": true
    }
  }
}

note

All social media platforms (14 total) are flat at the data level, not nested. This makes integration much easier!

Bonus: Verify an Email

Use SpiderVerify to check if an email is deliverable:

cURL

curl -X POST https://spideriq.ai/api/v1/jobs/spiderVerify/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <client_id>:<api_key>:<api_secret>" \
  -d '{
    "payload": {
      "email": "john@example.com"
    }
  }'

Python

response = requests.post(
    "https://spideriq.ai/api/v1/jobs/spiderVerify/submit",
    headers=headers,
    json={
        "payload": {
            "email": "john@example.com"
        }
    }
)
print(f"Verification job: {response.json()['job_id']}")

Response includes:

• status: valid, invalid, risky, or unknown
• quality_score: 0-100 rating
• is_disposable: temporary email service
• is_role_account: info@, support@, etc.

Next Steps

📖

Explore Guides

Learn advanced scraping techniques

💻

API Reference

View complete API documentation