Dashboard Playbooks

GET/api/v1/playbooks

List Playbooks

List playbooks for the authenticated user.

Supports filtering by:

status: queued, processing, completed, failed, paused
playbook_type: basic, plus
active_only: Only show playbooks with locations or companies (default: true)

Supports sorting by:

created_at, name, status, current_stage, companies_found, companies_processed, emails_verified

Parameters

Name	In	Type	Required	Description
`page`	query	integer	false
`page_size`	query	integer	false
`status`	query	any	false
`playbook_type`	query	any	false
`sort_by`	query	any	false	Field to sort by
`sort_order`	query	any	false	Sort order: asc or desc
`active_only`	query	boolean	false	Only show playbooks with actual workflow data

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/playbooks' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/playbooks",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/playbooks", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/playbooks

Create Playbook

Create a new playbook.

Supports both 'basic' (Maps → Site → Verify) and 'plus' (full pipeline) types.

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/playbooks' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/playbooks",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/playbooks", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/playbooks/{playbook_id}/status

Get Playbook Status

Get detailed status for a specific playbook.

Parameters

Name	In	Type	Required	Description
`playbook_id`	path	string	true

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/status' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/status",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/status", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/status", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

PATCH/api/v1/playbooks/{playbook_id}

Update Playbook

Update a playbook's configuration.

Allows updating:

name: Playbook display name
config: Worker configuration (spidermaps, spidersite, etc.)
priority: Job priority
webhook_url: Webhook for notifications
webhook_secret: Webhook signing secret

Parameters

Name	In	Type	Required	Description
`playbook_id`	path	string	true

Try it

Examples

cURL

curl -X PATCH 'https://spideriq.ai/api/v1/playbooks/{playbook_id}' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Python

import httpx

resp = httpx.patch(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{}`)
	req, _ := http.NewRequest("PATCH", "https://spideriq.ai/api/v1/playbooks/{playbook_id}", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/playbooks/{playbook_id}/results

Get Playbook Results

Get results (companies) for a specific playbook.

Parameters

Name	In	Type	Required
`playbook_id`	path	string	true
`page`	query	integer	false
`page_size`	query	integer	false

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/results' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/results",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/results", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/results", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/playbooks/{playbook_id}/pause

Pause Playbook

Pause a running playbook.

Parameters

Name	In	Type	Required	Description
`playbook_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/pause' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/pause",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/pause", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/pause", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/playbooks/{playbook_id}/resume

Resume Playbook

Resume a paused playbook.

Parameters

Name	In	Type	Required	Description
`playbook_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/resume' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/resume",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/resume", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/resume", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/playbooks/{playbook_id}/cancel

Cancel Playbook

Cancel a playbook.

Parameters

Name	In	Type	Required	Description
`playbook_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/cancel' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/cancel",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/cancel", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/cancel", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/playbooks/{playbook_id}/retry

Retry Playbook

Retry a playbook by re-submitting it with the same configuration.

Creates a new playbook with the same settings as the original. Works for completed, failed, or cancelled playbooks.

Parameters

Name	In	Type	Required	Description
`playbook_id`	path	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/retry' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/retry",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/retry", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/retry", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/playbooks/{playbook_id}/locations/{location_id}/stop

Stop Stuck Location

Stop a stuck location job.

Marks the location as failed and cancels any pending/processing jobs. Use this when a location is stuck for too long.

Parameters

Name	In	Type	Required	Description
`playbook_id`	path	string	true
`location_id`	path	integer	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/locations/{location_id}/stop' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/locations/{location_id}/stop",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/locations/{location_id}/stop", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/locations/{location_id}/stop", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/playbooks/{playbook_id}/runs

Get Playbook Runs

Get Inngest workflow runs for a playbook.

Returns the list of workflow executions with their status and timing.

Parameters

Name	In	Type	Required
`playbook_id`	path	string	true
`page`	query	integer	false
`page_size`	query	integer	false

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/runs' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/runs",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/runs", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/runs", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/playbooks/{playbook_id}/runs/{run_id}

Get Playbook Run Detail

Get detailed information about a specific workflow run.

Includes waterfall trace data if available.

Parameters

Name	In	Type	Required	Description
`playbook_id`	path	string	true
`run_id`	path	integer	true

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/playbooks/{playbook_id}/runs/{run_id}' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/playbooks/{playbook_id}/runs/{run_id}",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/playbooks/{playbook_id}/runs/{run_id}", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/playbooks/{playbook_id}/runs/{run_id}", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error