List Tracking

Retrieve all tracking configurations associated with your API key, including their status, performance metrics, and configuration details.

Endpoint

HTTP Request

GET /tracking
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Query Parameters

limit

Type: Integer
Description: Number of tracking configurations per page
Default: 20
Maximum: 100
Example: ?limit=50

status

Type: String
Description: Filter tracking configurations by status
Options: active, inactive, paused, error
Example: ?status=active

type

Type: String
Description: Filter by tracking type
Options: keyword, user, topic
Example: ?type=keyword

search

Type: String
Description: Search tracking configurations by name or description
Example: ?search=javascript

sort

Type: String
Description: Sort field and direction
Options: created_at, updated_at, name, items_tracked
Format: field:asc or field:desc
Default: created_at:desc
Example: ?sort=items_tracked:desc

Response Format

Success Response (200 OK)

{
  "data": [
    {
      "id": "tracking_1234567890",
      "name": "JavaScript Programming Tracker",
      "type": "keyword",
      "config": {
        "keywords": ["javascript", "programming", "web development"],
        "hashtags": ["#javascript", "#programming", "#webdev"],
        "language": "en",
        "min_followers": 1000,
        "verified_only": true
      },
      "filters": {
        "sentiment": "neutral",
        "engagement_min": 10
      },
      "delivery": {
        "method": "webhook",
        "webhook_id": "webhook_1234567890",
        "batch_size": 100,
        "frequency": "realtime"
      },
      "active": true,
      "description": "Track JavaScript programming content from verified users",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "statistics": {
        "items_tracked": 15420,
        "last_item_at": "2024-01-15T10:25:00Z",
        "daily_average": 1250,
        "success_rate": 99.8,
        "error_count": 3
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  },
  "summary": {
    "total_tracking": 45,
    "active_tracking": 38,
    "inactive_tracking": 5,
    "paused_tracking": 2,
    "total_items_tracked": 1250000,
    "average_daily_items": 85000
  }
}

Tracking Object Fields

Basic Information

id: Unique tracking identifier
name: Human-readable tracking name
type: Tracking type (keyword, user, topic)
active: Whether tracking is currently active
description: Detailed description of tracking purpose

Configuration

config: Main tracking configuration
filters: Additional filtering criteria
delivery: Data delivery configuration

Status Information

status: Current tracking status
- active: Tracking is running and collecting data
- inactive: Tracking is disabled
- paused: Tracking is temporarily paused
- error: Tracking has encountered errors

Timestamps

created_at: When tracking was created
updated_at: When tracking was last updated

Statistics

items_tracked: Total number of items tracked
last_item_at: Timestamp of last tracked item
daily_average: Average items tracked per day
success_rate: Percentage of successful data collection
error_count: Number of errors encountered

Implementation Examples

JavaScript (Node.js)

const axios = require("axios");

async function listTracking(apiKey, options = {}) {
  try {
    const params = new URLSearchParams();

    if (options.page) params.append("page", options.page);
    if (options.limit) params.append("limit", options.limit);
    if (options.status) params.append("status", options.status);
    if (options.type) params.append("type", options.type);
    if (options.search) params.append("search", options.search);
    if (options.sort) params.append("sort", options.sort);

    const response = await axios.get(`https://scrape.st/tracking?${params}`, {
      headers: {
        "x-api-key": apiKey,
        "Content-Type": "application/json",
      },
    });

    const tracking = response.data;
    console.log(`Found ${tracking.pagination.total} tracking configurations`);

    // Analyze tracking performance
    analyzeTrackingPerformance(tracking.data);

    return tracking;
  } catch (error) {
    console.error("Failed to list tracking:", error.response?.data || error.message);
    throw error;
  }
}

function analyzeTrackingPerformance(trackingConfigs) {
  console.log("\n=== Tracking Performance Analysis ===");

  trackingConfigs.forEach((config) => {
    const status = config.status === "active" ? "✅" : "❌";
    const efficiency = config.statistics.success_rate;

    console.log(`${status} ${config.id}`);
    console.log(`  Name: ${config.name}`);
    console.log(`  Type: ${config.type}`);
    console.log(`  Items Tracked: ${config.statistics.items_tracked.toLocaleString()}`);
    console.log(`  Daily Average: ${config.statistics.daily_average.toLocaleString()}`);
    console.log(`  Success Rate: ${efficiency.toFixed(2)}%`);

    if (config.statistics.error_count > 0) {
      console.log(`  Errors: ${config.statistics.error_count}`);
    }

    console.log("");
  });
}

// Usage
listTracking("your_api_key_here", {
  status: "active",
  type: "keyword",
  sort: "items_tracked:desc",
  limit: 50,
});

Python

import requests
from datetime import datetime

def list_tracking(api_key, **options):
    params = {}
    if 'page' in options:
        params['page'] = options['page']
    if 'limit' in options:
        params['limit'] = options['limit']
    if 'status' in options:
        params['status'] = options['status']
    if 'type' in options:
        params['type'] = options['type']
    if 'search' in options:
        params['search'] = options['search']
    if 'sort' in options:
        params['sort'] = options['sort']

    headers = {
        "x-api-key": api_key,
        "Content-Type": "application/json"
    }

    try:
        response = requests.get("https://scrape.st/tracking",
                             params=params, headers=headers)
        response.raise_for_status()
        tracking = response.json()

        print(f"Found {tracking['pagination']['total']} tracking configurations")

        # Analyze tracking performance
        analyze_tracking_performance(tracking['data'])

        return tracking
    except requests.exceptions.RequestException as error:
        print(f"Failed to list tracking: {error}")
        if error.response:
            print(f"Error details: {error.response.text}")
        raise

def analyze_tracking_performance(tracking_configs):
    print("\n=== Tracking Performance Analysis ===")

    for config in tracking_configs:
        status = "✅" if config['status'] == 'active' else "❌"
        efficiency = config['statistics']['success_rate']

        print(f"{status} {config['id']}")
        print(f"  Name: {config['name']}")
        print(f"  Type: {config['type']}")
        print(f"  Items Tracked: {config['statistics']['items_tracked']:,}")
        print(f"  Daily Average: {config['statistics']['daily_average']:,}")
        print(f"  Success Rate: {efficiency:.2f}%")

        if config['statistics']['error_count'] > 0:
            print(f"  Errors: {config['statistics']['error_count']}")

        print()

# Usage
list_tracking("your_api_key_here",
             status="active",
             type="keyword",
             sort="items_tracked:desc",
             limit=50)

cURL

# List all tracking configurations
curl -X GET "https://scrape.st/tracking" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# List active keyword tracking with pagination
curl -X GET "https://scrape.st/tracking?status=active&type=keyword&page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Search and sort tracking configurations
curl -X GET "https://scrape.st/tracking?search=javascript&sort=items_tracked:desc" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Advanced Filtering and Sorting

Status-Based Filtering

// Get tracking by status
const activeTracking = await listTracking(apiKey, { status: "active" });
const inactiveTracking = await listTracking(apiKey, { status: "inactive" });
const errorTracking = await listTracking(apiKey, { status: "error" });

Type-Based Filtering

// Get tracking by type
const keywordTracking = await listTracking(apiKey, { type: "keyword" });
const userTracking = await listTracking(apiKey, { type: "user" });
const topicTracking = await listTracking(apiKey, { type: "topic" });

Search Functionality

// Search tracking configurations
const jsTracking = await listTracking(apiKey, {
  search: "javascript",
});

const brandTracking = await listTracking(apiKey, {
  search: "brand monitoring",
});

Sorting Options

// Sort by different fields
const byItemsTracked = await listTracking(apiKey, {
  sort: "items_tracked:desc",
});

const byName = await listTracking(apiKey, {
  sort: "name:asc",
});

const byCreatedDate = await listTracking(apiKey, {
  sort: "created_at:desc",
});

Pagination Handling

async function getAllTracking(apiKey) {
  let allTracking = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await listTracking(apiKey, { page, limit: 100 });
    allTracking = allTracking.concat(response.data);

    hasMore = response.pagination.hasNext;
    page++;
  }

  return allTracking;
}

Performance Monitoring

Tracking Health Analysis

function analyzeTrackingHealth(trackingConfigs) {
  const healthReport = {
    total: trackingConfigs.length,
    active: 0,
    inactive: 0,
    paused: 0,
    error: 0,
    averageSuccessRate: 0,
    problematicTracking: [],
    topPerformers: [],
  };

  let totalSuccessRate = 0;

  trackingConfigs.forEach((config) => {
    // Count by status
    switch (config.status) {
      case "active":
        healthReport.active++;
        break;
      case "inactive":
        healthReport.inactive++;
        break;
      case "paused":
        healthReport.paused++;
        break;
      case "error":
        healthReport.error++;
        break;
    }

    const successRate = config.statistics.success_rate;
    totalSuccessRate += successRate;

    // Identify problematic tracking
    if (successRate < 95 || config.statistics.error_count > 10) {
      healthReport.problematicTracking.push({
        id: config.id,
        name: config.name,
        successRate,
        errors: config.statistics.error_count,
      });
    }

    // Identify top performers
    if (successRate > 99 && config.statistics.items_tracked > 1000) {
      healthReport.topPerformers.push({
        id: config.id,
        name: config.name,
        successRate,
        itemsTracked: config.statistics.items_tracked,
      });
    }
  });

  healthReport.averageSuccessRate = totalSuccessRate / trackingConfigs.length;

  return healthReport;
}

Automated Monitoring

class TrackingMonitor {
  constructor(apiKey, checkInterval = 300000) {
    // 5 minutes
    this.apiKey = apiKey;
    this.checkInterval = checkInterval;
    this.alertThresholds = {
      minSuccessRate: 95,
      maxErrors: 10,
      minItemsPerDay: 100,
    };
  }

  start() {
    this.monitorInterval = setInterval(async () => {
      await this.performHealthCheck();
    }, this.checkInterval);

    console.log("Tracking monitoring started");
  }

  stop() {
    if (this.monitorInterval) {
      clearInterval(this.monitorInterval);
      console.log("Tracking monitoring stopped");
    }
  }

  async performHealthCheck() {
    try {
      const response = await listTracking(this.apiKey);
      const healthReport = analyzeTrackingHealth(response.data);

      this.evaluateHealth(healthReport);
    } catch (error) {
      console.error("Health check failed:", error);
    }
  }

  evaluateHealth(healthReport) {
    // Check for problematic tracking
    if (healthReport.problematicTracking.length > 0) {
      this.sendAlert("problematic_tracking", {
        count: healthReport.problematicTracking.length,
        tracking: healthReport.problematicTracking,
      });
    }

    // Check overall success rate
    if (healthReport.averageSuccessRate < this.alertThresholds.minSuccessRate) {
      this.sendAlert("low_success_rate", {
        rate: healthReport.averageSuccessRate,
        threshold: this.alertThresholds.minSuccessRate,
      });
    }

    // Check error tracking
    if (healthReport.error > 0) {
      this.sendAlert("error_tracking", {
        count: healthReport.error,
      });
    }
  }

  sendAlert(type, data) {
    console.warn(`🚨 Tracking Alert: ${type}`, data);
    // Implement your alert notification logic here
  }
}

Error Handling

Common Error Responses

401 Unauthorized

{
  "error": "Invalid API key",
  "code": 401,
  "timestamp": "2024-01-15T10:30:00Z"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": 429,
  "retryAfter": 60
}

Error Handling Implementation

async function listTrackingWithRetry(apiKey, options = {}, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await listTracking(apiKey, options);
    } catch (error) {
      if (error.response?.status === 429) {
        const retryAfter = error.response.data?.retryAfter || 60;
        console.log(`Rate limited, retrying in ${retryAfter} seconds...`);
        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (error.response?.status === 401) {
        throw new Error("Invalid API key");
      }

      if (attempt === maxRetries) {
        throw error;
      }

      const delay = Math.pow(2, attempt) * 1000;
      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Best Practices

For Monitoring

Regular Checks: Monitor tracking status and performance regularly
Alert Thresholds: Set appropriate alert thresholds for your use case
Performance Analysis: Track success rates and data volume
Proactive Maintenance: Address issues before they become critical

For Performance

Pagination: Use pagination for large tracking lists
Filtering: Use specific filters to reduce data volume
Caching: Cache tracking data to reduce API calls
Batch Operations: Process multiple tracking configurations together

For Management

Regular Reviews: Periodically review tracking configurations
Optimization: Optimize tracking based on performance data
Documentation: Document tracking purposes and configurations
Cleanup: Remove or deactivate unused tracking configurations

Next: Delete Tracking

​List Tracking

​Endpoint

​HTTP Request

​Query Parameters

​page

​limit

​status

​type

​search

​sort

​Response Format

​Success Response (200 OK)

​Tracking Object Fields

​Basic Information

​Configuration

​Status Information

​Timestamps

​Statistics

​Implementation Examples

​JavaScript (Node.js)

​Python

​cURL

​Advanced Filtering and Sorting

​Status-Based Filtering

​Type-Based Filtering

​Search Functionality

​Sorting Options

​Pagination Handling

​Performance Monitoring

​Tracking Health Analysis

​Automated Monitoring

​Error Handling

​Common Error Responses

​401 Unauthorized

​429 Too Many Requests

​Error Handling Implementation

​Best Practices

​For Monitoring

​For Performance

​For Management

List Tracking

Endpoint

HTTP Request

Query Parameters

page

limit

status

type

search

sort

Response Format

Success Response (200 OK)

Tracking Object Fields

Basic Information

Configuration

Status Information

Timestamps

Statistics

Implementation Examples

JavaScript (Node.js)

Python

cURL

Advanced Filtering and Sorting

Status-Based Filtering

Type-Based Filtering

Search Functionality

Sorting Options

Pagination Handling

Performance Monitoring

Tracking Health Analysis

Automated Monitoring

Error Handling

Common Error Responses

401 Unauthorized

429 Too Many Requests

Error Handling Implementation

Best Practices

For Monitoring

For Performance

For Management