Create Tracking

Create a new tracking configuration to monitor specific Twitter/X accounts, keywords, hashtags, and topics based on your criteria.

Endpoint

HTTP Request

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

Request Body

{
  "name": "JavaScript Programming Tracker",
  "type": "keyword",
  "config": {
    "keywords": ["javascript", "programming", "web development"],
    "hashtags": ["#javascript", "#programming", "#webdev"],
    "users": ["twitter_user", "another_user"],
    "language": "en",
    "min_followers": 1000,
    "verified_only": true,
    "exclude_retweets": false
  },
  "filters": {
    "sentiment": "neutral",
    "engagement_min": 10,
    "date_range": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-12-31T23:59:59Z"
    }
  },
  "delivery": {
    "method": "webhook",
    "webhook_id": "webhook_1234567890",
    "batch_size": 100,
    "frequency": "realtime"
  },
  "active": true,
  "description": "Track JavaScript programming content from verified users"
}

Request Parameters

Required Parameters

name

Type: String
Description: Human-readable name for the tracking configuration
Max Length: 255 characters
Example: JavaScript Programming Tracker

type

Type: String
Description: Type of tracking configuration
Options:
- keyword: Track specific keywords and hashtags
- user: Track specific user accounts
- topic: Track broader topics and trends
Example: keyword

config

Type: Object
Description: Main tracking configuration
Properties: Varies by tracking type

Configuration Properties

Keyword Tracking (type: “keyword”)

{
  "keywords": ["javascript", "programming"],
  "hashtags": ["#javascript", "#programming"],
  "users": ["twitter_user"],
  "language": "en",
  "min_followers": 1000,
  "verified_only": true,
  "exclude_retweets": false
}

keywords: Array of keywords to track
hashtags: Array of hashtags to track
users: Array of specific users to include
language: Language code (e.g., “en”, “es”, “fr”)
min_followers: Minimum follower count for users
verified_only: Only track verified users
exclude_retweets: Exclude retweets from results

User Tracking (type: “user”)

{
  "users": ["twitter_user", "another_user"],
  "include_retweets": true,
  "include_replies": true,
  "track_mentions": true
}

users: Array of usernames to track
include_retweets: Include user’s retweets
include_replies: Include user’s replies
track_mentions: Track mentions of tracked users

Topic Tracking (type: “topic”)

{
  "topic": "artificial intelligence",
  "related_terms": ["AI", "machine learning", "deep learning"],
  "trending_threshold": 1000,
  "sentiment_analysis": true
}

topic: Main topic to track
related_terms: Related terms and keywords
trending_threshold: Minimum mentions for trending detection
sentiment_analysis: Enable sentiment analysis

Optional Parameters

filters

Type: Object
Description: Additional filtering criteria
Properties:
- sentiment: Filter by sentiment (“positive”, “negative”, “neutral”)
- engagement_min: Minimum engagement count
- date_range: Date range for tracking

delivery

Type: Object
Description: Data delivery configuration
Properties:
- method: Delivery method (“webhook”, “api”, “stream”)
- webhook_id: Webhook ID for webhook delivery
- batch_size: Number of items per batch
- frequency: Delivery frequency (“realtime”, “hourly”, “daily”)

active

Type: Boolean
Description: Whether tracking should be immediately active
Default: true
Example: true

description

Type: String
Description: Detailed description of tracking purpose
Max Length: 1000 characters
Example: Track JavaScript programming content from verified users

Response Format

Success Response (201 Created)

{
  "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": 0,
    "last_item_at": null,
    "daily_average": 0
  }
}

Error Response (400 Bad Request)

{
  "error": "Invalid tracking configuration",
  "code": 400,
  "details": {
    "field": "config.keywords",
    "message": "At least one keyword is required for keyword tracking"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_1234567890"
}

Implementation Examples

JavaScript (Node.js)

const axios = require("axios");

async function createTracking(apiKey, trackingConfig) {
  try {
    const response = await axios.post("https://scrape.st/tracking", trackingConfig, {
      headers: {
        "x-api-key": apiKey,
        "Content-Type": "application/json",
      },
    });

    const tracking = response.data;
    console.log("Tracking created successfully:", tracking.id);

    // Store tracking details
    await storeTrackingDetails(tracking);

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

function storeTrackingDetails(tracking) {
  // Store tracking details for monitoring
  console.log("Storing tracking details...");
  console.log("Tracking ID:", tracking.id);
  console.log("Name:", tracking.name);
  console.log("Type:", tracking.type);
  // Implement your storage logic here
}

// Create keyword tracking
const keywordTracking = {
  name: "JavaScript Programming Tracker",
  type: "keyword",
  config: {
    keywords: ["javascript", "programming", "web development"],
    hashtags: ["#javascript", "#programming", "#webdev"],
    language: "en",
    min_followers: 1000,
    verified_only: true,
    exclude_retweets: false,
  },
  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",
};

createTracking("your_api_key_here", keywordTracking);

Python

import requests
import json

def create_tracking(api_key, tracking_config):
    url = "https://scrape.st/tracking"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    try:
        response = requests.post(url, json=tracking_config, headers=headers)
        response.raise_for_status()
        tracking = response.json()

        print(f"Tracking created successfully: {tracking['id']}")

        # Store tracking details
        store_tracking_details(tracking)

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

def store_tracking_details(tracking):
    print("Storing tracking details...")
    print(f"Tracking ID: {tracking['id']}")
    print(f"Name: {tracking['name']}")
    print(f"Type: {tracking['type']}")
    # Implement your storage logic here

# Create keyword tracking
keyword_tracking = {
    "name": "JavaScript Programming Tracker",
    "type": "keyword",
    "config": {
        "keywords": ["javascript", "programming", "web development"],
        "hashtags": ["#javascript", "#programming", "#webdev"],
        "language": "en",
        "min_followers": 1000,
        "verified_only": True,
        "exclude_retweets": False
    },
    "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"
}

create_tracking("your_api_key_here", keyword_tracking)

cURL

curl -X POST https://scrape.st/tracking \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "JavaScript Programming Tracker",
    "type": "keyword",
    "config": {
      "keywords": ["javascript", "programming", "web development"],
      "hashtags": ["#javascript", "#programming", "#webdev"],
      "language": "en",
      "min_followers": 1000,
      "verified_only": true,
      "exclude_retweets": false
    },
    "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"
  }'

Advanced Configurations

Boolean Logic Tracking

const booleanTracking = {
  name: "Advanced Boolean Tracking",
  type: "keyword",
  config: {
    boolean_query: "(javascript OR programming) AND (tutorial OR guide) -spam",
    language: "en",
    verified_only: true,
  },
};

Geographic Filtering

const geographicTracking = {
  name: "Local Business Tracking",
  type: "keyword",
  config: {
    keywords: ["restaurant", "cafe", "shop"],
    location: {
      country: "US",
      city: "New York",
      radius: 50,
    },
  },
};

Sentiment-Based Tracking

const sentimentTracking = {
  name: "Brand Sentiment Tracking",
  type: "keyword",
  config: {
    keywords: ["your_brand", "YourBrand"],
    language: "en",
  },
  filters: {
    sentiment: ["positive", "negative"],
    engagement_min: 5,
  },
};

Error Handling

Common Error Codes

400 Bad Request

Invalid Configuration: Tracking configuration is malformed
Missing Required Fields: Required parameters are missing
Invalid Values: Parameter values are invalid

401 Unauthorized

Invalid API Key: API key is missing or invalid
Insufficient Permissions: API key lacks tracking creation permissions

409 Conflict

Duplicate Tracking: Similar tracking configuration already exists
Tracking Limit: Maximum number of tracking configurations reached

429 Too Many Requests

Rate Limit: Too many tracking creation requests
Retry After: Check Retry-After header for retry time

Error Handling Implementation

async function createTrackingWithRetry(apiKey, trackingConfig, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await createTracking(apiKey, trackingConfig);
    } catch (error) {
      if (error.response?.status === 429) {
        const retryAfter = error.response.headers["retry-after"] || 60;
        console.log(`Rate limited, retrying in ${retryAfter} seconds...`);
        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (error.response?.status === 409) {
        console.error("Tracking configuration already exists or limit reached");
        throw error;
      }

      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

Configuration Design

Specific Criteria: Use specific, relevant keywords and filters
Performance Optimization: Avoid overly broad tracking criteria
Testing: Test tracking configurations with small datasets first
Documentation: Document tracking purposes and configurations

Resource Management

Monitoring: Monitor tracking performance and data volume
Optimization: Regularly review and optimize tracking configurations
Cost Management: Consider data volume and processing costs
Scaling: Plan for scaling based on data volume

Data Quality

Validation: Validate tracking configuration before creation
Quality Checks: Monitor data quality and completeness
Filter Refinement: Continuously refine filters for better results
Performance Monitoring: Track tracking effectiveness and ROI

Next: List Tracking

​Create Tracking

​Endpoint

​HTTP Request

​Request Body

​Request Parameters

​Required Parameters

​name

​type

​config

​Configuration Properties

​Keyword Tracking (type: “keyword”)

​User Tracking (type: “user”)

​Topic Tracking (type: “topic”)

​Optional Parameters

​filters

​delivery

​active

​description

​Response Format

​Success Response (201 Created)

​Error Response (400 Bad Request)

​Implementation Examples

​JavaScript (Node.js)

​Python

​cURL

​Advanced Configurations

​Boolean Logic Tracking

​Geographic Filtering

​Sentiment-Based Tracking

​Error Handling

​Common Error Codes

​400 Bad Request

​401 Unauthorized

​409 Conflict

​429 Too Many Requests

​Error Handling Implementation

​Best Practices

​Configuration Design

​Resource Management

​Data Quality

Create Tracking

Endpoint

HTTP Request

Request Body

Request Parameters

Required Parameters

name

type

config

Configuration Properties

Keyword Tracking (type: “keyword”)

User Tracking (type: “user”)

Topic Tracking (type: “topic”)

Optional Parameters

filters

delivery

active

description

Response Format

Success Response (201 Created)

Error Response (400 Bad Request)

Implementation Examples

JavaScript (Node.js)

Python

cURL

Advanced Configurations

Boolean Logic Tracking

Geographic Filtering

Sentiment-Based Tracking

Error Handling

Common Error Codes

400 Bad Request

401 Unauthorized

409 Conflict

429 Too Many Requests

Error Handling Implementation

Best Practices

Configuration Design

Resource Management

Data Quality