Events

2 endpoints from the published OpenAPI import.

GET/api/v1/events/stream

Stream Events

Server-Sent Events stream for real-time job monitoring.

Connect to this endpoint to receive live job events for your client account. Events are streamed as they happen - no polling required.

Authentication: Pass your credentials as a query parameter:

GET /api/v1/events/stream?token=client_id:api_key:api_secret

Optional server-side filtering: Append ?campaign_id=<id> or ?job_id=<id> to receive only the matching events (plus the connected handshake and heartbeat keep-alives). With no filter you get the full client-scoped firehose (unchanged, default). Filters are a union — supplying both shows events matching either id.

GET /api/v1/events/stream?token=...&campaign_id=camp_abc
GET /api/v1/events/stream?token=...&job_id=550e8400-...

Event Types:

connected: Sent when connection is established
job.queued: Job submitted and queued for processing
job.started: Worker picked up the job
job.completed: Job finished successfully
job.failed: Job encountered an error
campaign.terminal: A campaign reached a terminal state (the definitive "done" signal — carries the chosen status + success_pct)
heartbeat: Keep-alive signal (every 30 seconds)

Event Format (SSE):

event: job.completed
data: {"job_id": "abc-123", "processing_time": 45.2, "results_count": 15}

JavaScript Example:

const token = 'cli_xxx:sk_xxx:secret_xxx';
const eventSource = new EventSource(
  `https://spideriq.ai/api/v1/events/stream?token=${token}`
);

eventSource.addEventListener('job.completed', (e) => {
  const data = JSON.parse(e.data);
  console.log('Job completed:', data.job_id);
});

Returns: SSE stream of job events

Parameters

Name	In	Type	Required	Description
`campaign_id`	query	any	false	Optional. Deliver only events for this campaign (plus connected/heartbeat). Note: per-job events carry no campaign id — use job_id to watch a single job.
`job_id`	query	any	false	Optional. Deliver only events for this job (plus connected/heartbeat).
`token`	query	any	false	Auth token (client_id:api_key:api_secret)

Try it

Examples

cURL

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

Python

import httpx

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

JavaScript

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

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/events/stream", 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/events/status

Get Event Status

Get event service status.

Returns: Event service health and active subscription count