API Reference

https://adspyre.com/api

GET /api/v1/account
X-Api-Key: as_live_your_key_here

{
  "success": true,
  "message": "OK",
  "tariff": "Pro",
  "credits_available": 18450,
  "credits_reserved": 550,
  "credits_used": 6000,
  "credits_per_month": 25000,
  "credits_used_percent": 26.2,
  "plan_expires": "2025-12-31 23:59:59",
  "max_concurrent_tasks": 3,
  "active_tasks": 1,
  "retention_days": 30,
  "threads": 4
}

GET /api/v1/tasks?page=1&per_page=20&status=completed
X-Api-Key: as_live_your_key_here

{
  "success": true,
  "message": "Tasks fetched",
  "tasks": [
    {
      "id": 42,
      "status": "completed",
      "target_query": "nike shoes",
      "found_ads": 350,
      "credits_limit": 500,
      "credits_reserved": 0,
      "credits_spent": 350,
      "created_at": "2025-11-10 14:22:00",
      "updated_at": "2025-11-10 14:24:38"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 87,
    "total_pages": 5
  }
}

POST /api/v1/tasks
X-Api-Key: as_live_your_key_here
Content-Type: application/json

{
  "query": "nike shoes",
  "credits_limit": 500,
  "filters": {
    "country": "US",
    "active_status": "ACTIVE",
    "media_type": "ALL",
    "search_type": "KEYWORD_UNORDERED",
    "sort_mode": "RELEVANCY_MONTHLY_GROUPED",
    "sort_direction": "DESCENDING",
    "publisher_platforms": ["facebook", "instagram"],
    "content_languages": "en",
    "advertiser_id": "",
    "start_date_min": "",
    "start_date_max": "",
    "result_count": 500,
    "get_eu_info": false,
    "is_targeted_country": false
  },
  "notifications": {}
}

{
  "success": true,
  "message": "Task created and added to queue",
  "task_id": 43,
  "credits_held": 500
}

GET /api/v1/results?task_id=43&page=1&per_page=50
X-Api-Key: as_live_your_key_here

{
  "success": true,
  "message": "Results fetched",
  "task": {
    "id": 43,
    "target_query": "nike shoes",
    "status": "completed",
    "found_ads": 350,
    "credits_reserved": 0,
    "created_at": "2025-11-10 14:22:00",
    "updated_at": "2025-11-10 14:24:38",
    "execution_time": "2m 38s"
  },
  "results": [
    {
      "id": 1001,
      "ad_archive_id": "123456789",
      "published_at": "2025-10-01 08:00:00",
      "stop_at": null,
      "page_id": "987654321",
      "page_name": "Nike",
      "page_url": "https://www.facebook.com/nike",
      "page_picture": "https://...",
      "captions": ["Just Do It"],
      "cta_text": ["Shop Now"],
      "cta_type": ["SHOP_NOW"],
      "display_format": "VIDEO",
      "links": ["https://nike.com/..."],
      "platforms": ["facebook", "instagram"],
      "body_text": ["Introducing the Air Max 2025..."],
      "link_description": ["New collection — limited time offer"],
      "images": ["https://..."],
      "videos": ["https://..."],
      "created_at": "2025-11-10 14:23:11"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 350,
    "total_pages": 7
  }
}

{
  "success": false,
  "message": "Human-readable description",
  "code": "MACHINE_READABLE_CODE"
}

# Account info
curl -H "X-Api-Key: as_live_your_key" \
  https://adspyre.com/api/v1/account

# Create task
curl -X POST \
  -H "X-Api-Key: as_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query":"nike","credits_limit":200,"filters":{"country":"US","result_count":200}}' \
  https://adspyre.com/api/v1/tasks

# Poll task list
curl -H "X-Api-Key: as_live_your_key" \
  "https://adspyre.com/api/v1/tasks?status=completed&per_page=5"

# Fetch results
curl -H "X-Api-Key: as_live_your_key" \
  "https://adspyre.com/api/v1/results?task_id=43&per_page=50"

const API_KEY = 'as_live_your_key';
const BASE    = 'https://adspyre.com/api';

const headers = { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' };

// Create a task
const { task_id } = await fetch(`${BASE}/v1/tasks`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    query: 'nike shoes',
    credits_limit: 300,
    filters: { country: 'US', result_count: 300 },
  }),
}).then(r => r.json());

// Poll until completed
let status = 'pending';
while (status === 'pending' || status === 'processing') {
  await new Promise(r => setTimeout(r, 5000));
  const tasks = await fetch(`${BASE}/v1/tasks?per_page=1&page=1`, { headers }).then(r => r.json());
  status = tasks.tasks.find(t => t.id === task_id)?.status ?? status;
}

// Fetch results (page 1)
const data = await fetch(`${BASE}/v1/results?task_id=${task_id}&per_page=100`, { headers })
  .then(r => r.json());

console.log(data.results);

import requests, time

API_KEY = "as_live_your_key"
BASE    = "https://adspyre.com/api"
HEADERS = {"X-Api-Key": API_KEY, "Content-Type": "application/json"}

# Create task
res = requests.post(f"{BASE}/v1/tasks", json={
    "query": "nike shoes",
    "credits_limit": 300,
    "filters": {"country": "US", "result_count": 300},
}, headers=HEADERS)
task_id = res.json()["task_id"]

# Poll until done
while True:
    tasks = requests.get(f"{BASE}/v1/tasks", params={"per_page": 100}, headers=HEADERS).json()
    task  = next((t for t in tasks["tasks"] if t["id"] == task_id), None)
    if task and task["status"] in ("completed", "failed"):
        break
    time.sleep(5)

# Fetch results
page, all_results = 1, []
while True:
    r = requests.get(f"{BASE}/v1/results", params={"task_id": task_id, "page": page, "per_page": 100}, headers=HEADERS).json()
    all_results.extend(r["results"])
    if page >= r["pagination"]["total_pages"]:
        break
    page += 1

print(f"Collected {len(all_results)} ads")