Proxy — SpiderIQ

POST/api/v1/proxy/request

Get a proxy from the pool

Request a proxy from the pool for making requests.

Selection Logic:

If sticky_session_id is provided, returns the same proxy if still valid
Filters by country_code or location_id if specified
Excludes any exclude_modem_ids
Selects from healthy modems using round-robin

Example:

    response = requests.post(
        "/api/v1/proxy/request",
        json={"country_code": "UA"},
        headers={"Authorization": f"Bearer {token}"}
    )
    proxy_url = response.json()["proxy_url"]

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/request' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "country_code": "string",
  "location_id": "00000000-0000-0000-0000-000000000000",
  "location_code": "string",
  "device_type": "any",
  "sticky_session_id": "string",
  "exclude_modem_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "exclude_iphone_ids": [
    "00000000-0000-0000-0000-000000000000"
  ]
}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/proxy/request",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"country_code": "string", "location_id": "00000000-0000-0000-0000-000000000000", "location_code": "string", "device_type": "any", "sticky_session_id": "string", "exclude_modem_ids": ["00000000-0000-0000-0000-000000000000"], "exclude_iphone_ids": ["00000000-0000-0000-0000-000000000000"]},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/request", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"country_code": "string", "location_id": "00000000-0000-0000-0000-000000000000", "location_code": "string", "device_type": "any", "sticky_session_id": "string", "exclude_modem_ids": ["00000000-0000-0000-0000-000000000000"], "exclude_iphone_ids": ["00000000-0000-0000-0000-000000000000"]})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"country_code": "string", "location_id": "00000000-0000-0000-0000-000000000000", "location_code": "string", "device_type": "any", "sticky_session_id": "string", "exclude_modem_ids": ["00000000-0000-0000-0000-000000000000"], "exclude_iphone_ids": ["00000000-0000-0000-0000-000000000000"]}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/proxy/request", 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/proxy/pool/roundrobin

Get next proxy (round-robin)

Simple round-robin proxy selection. Each call returns the next available proxy in rotation.

Optionally filter by country code.

Like Proxidize's Proxy Pooling feature.

Parameters

Name	In	Type	Required	Description
`country_code`	query	any	false	Filter by country

Try it

Examples

cURL

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

Python

import httpx

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

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/pool/roundrobin", {
  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/proxy/pool/roundrobin", 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/proxy/pool

List available proxies

List all available proxies in the pool.

Similar to Proxidize's /api/getinfo endpoint.

Parameters

Name	In	Type	Required	Description
`country_code`	query	any	false
`location_id`	query	any	false
`healthy_only`	query	boolean	false	Only return healthy modems

Try it

Examples

cURL

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

Python

import httpx

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

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/pool", {
  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/proxy/pool", 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/proxy/stats

Get pool statistics

Get aggregate statistics about the proxy pool.

Try it

Examples

cURL

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

Python

import httpx

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

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/stats", {
  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/proxy/stats", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response

POST/api/v1/proxy/rotate

Request IP rotation

Request IP rotation for a specific modem.

The rotation is queued and executed by the agent. Returns immediately with the command status.

Rotation Methods:

reconnect: Disconnect and reconnect (fastest, ~5-15 seconds)
airplane: Toggle airplane mode (~10-20 seconds)
reboot: Full modem reboot (slowest, ~30-60 seconds)

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/rotate' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "modem_id": "00000000-0000-0000-0000-000000000000",
  "method": "reconnect",
  "reason": "string"
}'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/proxy/rotate",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"modem_id": "00000000-0000-0000-0000-000000000000", "method": "reconnect", "reason": "string"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/rotate", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"modem_id": "00000000-0000-0000-0000-000000000000", "method": "reconnect", "reason": "string"})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"modem_id": "00000000-0000-0000-0000-000000000000", "method": "reconnect", "reason": "string"}`)
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/proxy/rotate", 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

POST/api/v1/proxy/rotate-all

Rotate all modems

Request IP rotation for all online modems.

Optionally filter by location.

Similar to Proxidize's /api/rotate endpoint.

Parameters

Name	In	Type	Required	Description
`location_id`	query	any	false	Filter by location
`method`	query	any	false

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/rotate-all' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

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

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/rotate-all", {
  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/proxy/rotate-all", 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/proxy/report

Report proxy failure

Report a proxy failure.

After 3 failures within 5 minutes, the modem is marked as unhealthy. Call this when a proxy request fails (timeout, blocked, etc.).

Parameters

Name	In	Type	Required	Description
`modem_id`	query	string	true
`error`	query	string	true	Error description

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/report' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

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

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/report", {
  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/proxy/report", 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/proxy/report-success

Report proxy success

Report a successful proxy request. Resets failure counter.

Parameters

Name	In	Type	Required	Description
`modem_id`	query	string	true

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/proxy/report-success' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

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

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/proxy/report-success", {
  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/proxy/report-success", 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