🧪 Backlab SDK

Official JavaScript SDK for Backlab AI-Powered Web Scraping API. https://backlab.dev

🔥 Features

• ✅ AI-Powered Extraction: Use natural language to describe what you want to extract
• ✅ Cloudflare Bypass: Handles complex sites with browser automation
• ✅ TypeScript Support: Full type definitions included
• ✅ Rate Limiting: Built-in handling for API limits
• ✅ Error Handling: Comprehensive error management
• ✅ Async/Await: Modern JavaScript API

📦 Installation

npm install backlab-sdk

🔑 Quick Start

import { Backlab } from 'backlab-sdk';

const backlab = new Backlab({
  apiKey: 'your-api-key-here'
});

// Extract data using AI
const result = await backlab.web.ai_scrape({
  url: "https://example.com",
  element_prompts: {
    title: {
      description: "The main title of the page"
    },
    price: {
      description: "Product price"
    }
  }
});

console.log(result.data);

🎯 Examples

Basic Scraping

import { Backlab } from 'backlab-sdk';

const backlab = new Backlab({
  apiKey: process.env.BACKLAB_API_KEY
});

const result = await backlab.web.ai_scrape({
  url: "https://openai.com/api/pricing/",
  element_prompts: {
    model_name: {
      description: "Name of the OpenAI model"
    },
    pricing: {
      description: "Pricing information per token"
    }
  }
});

if (result.status === 'completed') {
  result.data.forEach(item => {
    console.log(`${item.model_name}: ${item.pricing}`);
  });
}

Advanced Configuration

const result = await backlab.web.ai_scrape({
  url: "https://complex-site.com",
  element_prompts: {
    products: {
      description: "List of products with names and prices"
    }
  },
  options: {
    timeout: 30000,
    temperature: 0.1,
    max_tokens: 4000,
    include_html: false
  }
});

Check Usage

const usage = await backlab.usage.get();
console.log(`Credits remaining: ${usage.credits_remaining}`);
console.log(`Rate limit: ${usage.rate_limit.per_minute}/min`);

Error Handling

try {
  const result = await backlab.web.ai_scrape({
    url: "https://example.com",
    element_prompts: {
      title: { description: "Page title" }
    }
  });
  
  console.log(result.data);
} catch (error) {
  if (error.statusCode === 401) {
    console.error('Invalid API key');
  } else if (error.statusCode === 402) {
    console.error('Insufficient credits');
  } else if (error.statusCode === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Error:', error.message);
  }
}

📚 API Reference

Constructor

const backlab = new Backlab({
  apiKey: 'your-api-key',      // Required
  baseURL: 'custom-url',       // Optional
  timeout: 60000               // Optional (milliseconds)
});

Methods

web.ai_scrape(params)

Extract data from web pages using AI.

Parameters:

• url (string): URL to scrape
• element_prompts (object): Descriptions of what to extract
• options (object, optional): Scraping options

Returns: Promise<ScrapeResponse>

usage.get()

Get current usage statistics.

Returns: Promise<UsageResponse>

auth.validate()

Validate your API key.

Returns: Promise<ValidationResponse>

🔧 TypeScript Support

The SDK includes full TypeScript definitions:

import { Backlab, ScrapeRequest, ScrapeResponse } from 'backlab';

const backlab = new Backlab({
  apiKey: process.env.BACKLAB_API_KEY!
});

const request: ScrapeRequest = {
  url: "https://example.com",
  element_prompts: {
    title: {
      description: "Page title",
      required: true
    }
  }
};

const result: ScrapeResponse = await backlab.web.ai_scrape(request);

🏗️ Framework Integration

Express.js

import express from 'express';
import { Backlab } from 'backlab-sdk';

const app = express();
const backlab = new Backlab({ apiKey: process.env.BACKLAB_API_KEY });

app.post('/scrape', async (req, res) => {
  try {
    const result = await backlab.web.ai_scrape(req.body);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Next.js

// pages/api/scrape.js
import { Backlab } from 'backlab-sdk';

const backlab = new Backlab({ apiKey: process.env.BACKLAB_API_KEY });

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    const result = await backlab.web.ai_scrape(req.body);
    res.status(200).json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

📊 Rate Limits

| Plan | Requests/min | Requests/hour | Credits | |------|--------------|---------------|---------| | Free | 10 | 100 | 100 | | Pro | 60 | 1000 | 1000 | | Enterprise | 120 | 5000 | 10000 |

🔒 Security

• Never expose your API key in client-side code
• Use environment variables for API keys
• Implement rate limiting in your applications
• Validate URLs before scraping

📞 Support

• Documentation: https://backlab-api.up.railway.app/docs
• Email: [email protected]

📄 License

MIT License - see LICENSE file for details.

🎯 Links

• Official Website
• API Documentation