Get Campaign Status

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

Overview

Retrieve comprehensive status information for a campaign, including progress statistics, job counts by status, and configuration details.

tip

v2.15.0: For orchestrated campaigns, this endpoint includes workflow_progress showing SpiderSite and SpiderVerify job statistics.

Path Parameters

campaign_idstringrequired

The campaign ID

Response

campaign_idstring

The campaign identifier

statusstring

Campaign status: active, paused, completed, stopped

querystring

The search query used

country_codestring

The country code

filter_configobject

The filter configuration used to select locations

progressobject

Location progress statistics

Progress Properties

totalinteger

Total locations

pendinginteger

Not yet submitted

submittedinteger

Currently processing

completedinteger

Successfully completed

failedinteger

Failed jobs

percentagenumber

Completion percentage

jobsobject

Job status counts

Job Properties

queuedinteger

Jobs in queue

processinginteger

Jobs being processed

completedinteger

Completed jobs

failedinteger

Failed jobs

results_countinteger

Total businesses found across all completed jobs

has_workflowboolean

v2.15.0: Whether workflow orchestration is enabled

workflow_configobject

v2.15.0: Workflow configuration (only present if has_workflow is true)

workflow_progressobject

v2.15.0: Workflow chain progress statistics (only present if has_workflow is true)

Workflow Progress Properties

businesses_totalinteger

Total businesses with valid domains found

sites_queuedinteger

SpiderSite jobs currently queued

sites_completedinteger

SpiderSite jobs completed

sites_failedinteger

SpiderSite jobs failed

verifies_queuedinteger

SpiderVerify jobs currently queued

verifies_completedinteger

SpiderVerify jobs completed

verifies_failedinteger

SpiderVerify jobs failed

emails_foundinteger

Total emails extracted from websites

emails_verifiedinteger

Total emails that completed verification

created_atstring

Campaign creation timestamp

updated_atstring

Last update timestamp

Example

cURL

curl https://spideriq.ai/api/v1/jobs/spiderMaps/campaigns/camp_lu_restaurants_abc123/status \
  -H "Authorization: Bearer <your_token>"

Python

import requests

campaign_id = "camp_lu_restaurants_abc123"
response = requests.get(
    f"https://spideriq.ai/api/v1/jobs/spiderMaps/campaigns/{campaign_id}/status",
    headers={"Authorization": "Bearer <your_token>"}
)
status = response.json()

print(f"Status: {status['status']}")
print(f"Progress: {status['progress']['percentage']:.1f}%")
print(f"Completed: {status['progress']['completed']}/{status['progress']['total']}")
print(f"Businesses found: {status['results_count']}")

Response:

{
  "campaign_id": "camp_lu_restaurants_abc123",
  "status": "active",
  "query": "restaurants",
  "country_code": "LU",
  "filter_config": {
    "mode": "all"
  },
  "progress": {
    "total": 12,
    "pending": 4,
    "submitted": 3,
    "completed": 5,
    "failed": 0,
    "percentage": 41.67
  },
  "jobs": {
    "queued": 2,
    "processing": 1,
    "completed": 5,
    "failed": 0
  },
  "results_count": 523,
  "created_at": "2025-12-22T17:13:02Z",
  "updated_at": "2025-12-22T17:25:18Z"
}

Orchestrated Campaign Response (v2.15.0)

For campaigns with workflow orchestration enabled:

{
  "campaign_id": "camp_fr_restaurants_20251223_a1b2c3d4",
  "status": "active",
  "query": "restaurants",
  "country_code": "FR",
  "filter_config": {
    "mode": "population",
    "min_population": 100000
  },
  "progress": {
    "total": 42,
    "pending": 10,
    "submitted": 5,
    "completed": 27,
    "failed": 0,
    "percentage": 64.29
  },
  "jobs": {
    "queued": 3,
    "processing": 2,
    "completed": 27,
    "failed": 0
  },
  "results_count": 540,
  "has_workflow": true,
  "workflow_config": {
    "spidersite": {
      "enabled": true,
      "max_pages": 10
    },
    "spiderverify": {
      "enabled": true,
      "max_emails_per_business": 5
    }
  },
  "workflow_progress": {
    "businesses_total": 320,
    "sites_queued": 15,
    "sites_completed": 280,
    "sites_failed": 5,
    "verifies_queued": 20,
    "verifies_completed": 240,
    "verifies_failed": 2,
    "emails_found": 680,
    "emails_verified": 580
  },
  "created_at": "2025-12-23T10:30:00Z",
  "updated_at": "2025-12-23T12:15:00Z"
}

tip

Use the /workflow-results endpoint to get aggregated data from all three services once the campaign is complete.

Status Values

Status	Description
active	Campaign is running, /next will submit jobs
paused	Temporarily paused (use /continue to resume)
stopped	Manually stopped (use /continue to resume)
completed	All locations processed

Related Endpoints

⏸️

Stop Campaign

Pause a running campaign

▶️

Continue Campaign

Resume a stopped campaign

📐

Workflow Results

Get aggregated workflow results

📖

Orchestration Guide

Complete orchestration guide