Guide

Pro Feature

Bring Your Own Proxy (BYOP)

Connect your existing proxy subscriptions to AlterLab and use your own proxies while benefiting from our intelligent anti-bot technology.

Why Use BYOP?

Cost Optimization

Already have proxy subscriptions? Use them with AlterLab instead of paying twice. Your bandwidth, your proxies.

Provider Flexibility

Different providers excel at different sites. Mix and match providers for optimal coverage.

Geographic Control

Use proxies in specific countries or cities that your provider offers, even if AlterLab doesn't cover that region.

No Vendor Lock-in

Keep your existing relationships with proxy providers. Switch or combine as needed.

How Pricing Works with BYOP

When using your own proxy, AlterLab costs less since you're providing the proxy bandwidth. You still get our anti-bot technology, tier escalation, and content extraction at a reduced rate.

Supported Providers

Provider	Type	Required Credentials	Features
Bright Data	Residential, Datacenter, ISP	`username`, `password`, `zone`	Country/city targeting, session control
Oxylabs	Residential, Datacenter	`username`, `password`	Country targeting, sticky sessions
Smartproxy	Residential, Datacenter	`username`, `password`	Auto-rotation, country targeting
IPRoyal	Residential, Datacenter	`username`, `password`	Pay-as-you-go, country targeting
DataImpulse	Residential	`api_key`	Pay-per-GB, 195+ countries
Custom	Any HTTP/SOCKS5	`proxy_url`	Bring any proxy that supports standard protocols

Account Requirements

You need an active subscription with the proxy provider. AlterLab validates your credentials during setup and will show an error if your account is inactive or has insufficient balance.

How It Works

1. Request Arrives

When you make a scrape request, AlterLab checks if you have any BYOP integrations configured.

2. Proxy Selection

Based on your strategy (proactive or reactive), the domain's requirements, and integration priority, AlterLab selects the optimal proxy. BYOP integrations are preferred when available.

3. Intelligent Routing

Your request is routed through your proxy with AlterLab's anti-detection measures: TLS fingerprinting, header rotation, and stealth browser profiles.

4. Fallback Handling

If your proxy fails, AlterLab automatically escalates to higher tiers or falls back to AlterLab's proxy network (charged normally) to ensure request success.

Setup Guide

Step 1: Get Provider Credentials

Log into your proxy provider's dashboard and locate your API credentials. Different providers use different authentication methods:

Bright Data: Dashboard → Zones → Select Zone → Credentials
Oxylabs: Dashboard → Proxies → User Credentials
Smartproxy: Dashboard → Proxy Setup → Authentication
DataImpulse: Dashboard → API → API Key

Step 2: Add Integration via Dashboard

The easiest way to add a proxy integration is through the AlterLab dashboard:

Go to Dashboard → Integrations → Proxies
Click "Add Integration"
Select your proxy provider
Enter your credentials
Click "Test Connection" to verify
Save the integration

Step 3: Add Integration via API (Alternative)

You can also add integrations programmatically:

import requests

# Create a Bright Data integration
response = requests.post(
    "https://api.alterlab.io/api/v1/proxies",
    headers={
        "Authorization": "Bearer YOUR_SESSION_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "provider": "brightdata",
        "name": "My Bright Data Residential",
        "credentials": {
            "username": "brd-customer-xxx-zone-residential",
            "password": "your_password"
        },
        "is_default": True
    }
)

print(response.json())

Step 4: Test Your Integration

Verify the integration works before using it in production:

# Test the integration
response = requests.post(
    f"https://api.alterlab.io/api/v1/proxies/{integration_id}/test",
    headers={"Authorization": "Bearer YOUR_SESSION_TOKEN"},
    json={
        "test_url": "https://httpbin.org/ip",
        "timeout_seconds": 30
    }
)

result = response.json()
if result["success"]:
    print(f"Success! Proxy IP: {result['proxy_ip']}")
    print(f"Response time: {result['response_time_ms']}ms")
else:
    print(f"Failed: {result['error']}")

API Reference

Authentication

Proxy integration endpoints require session authentication (JWT token from dashboard login), not API key authentication. These are dashboard-linked operations.

List Supported Providers

GET

/api/v1/proxies/providers

Get list of all supported proxy providers with their configuration requirements.

Response Example

[
  {
    "id": "brightdata",
    "name": "Bright Data",
    "description": "Leading proxy provider with residential, datacenter, and ISP proxies",
    "website": "https://brightdata.com",
    "logo_url": "https://...",
    "credential_fields": [
      {"name": "username", "type": "text", "required": true},
      {"name": "password", "type": "password", "required": true},
      {"name": "zone", "type": "text", "required": false}
    ],
    "features": ["residential", "datacenter", "isp", "country_targeting", "city_targeting"]
  },
  // ... more providers
]

Create Integration

POST

/api/v1/proxies

Create a new proxy integration by connecting to a provider. Credentials are validated before saving.

Parameters

Name	Type	Required	Description
provider	`string`	Required	Provider ID: brightdata, oxylabs, smartproxy, iproyal, dataimpulse, custom
name	`string`	Required	Display name for this integration (unique per provider)
credentials	`object`	Required	Provider-specific credentials (username/password, api_key, etc.)
is_default	`boolean`	Optional	Set as default proxy for all requestsDefault: `false`

Request Example

curl -X POST https://api.alterlab.io/api/v1/proxies \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "oxylabs",
    "name": "Oxylabs Residential",
    "credentials": {
      "username": "customer_xxx",
      "password": "your_password"
    },
    "is_default": true
  }'

Response Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Oxylabs Residential",
  "provider": "oxylabs",
  "is_active": true,
  "is_default": true,
  "priority": 0,
  "validation_status": "valid",
  "last_validated_at": "2025-01-15T10:30:00Z",
  "validation_error": null,
  "total_requests": 0,
  "successful_requests": 0,
  "failed_requests": 0,
  "success_rate": 0.0,
  "last_used_at": null,
  "endpoints_count": 45,
  "endpoints_refreshed_at": "2025-01-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

List Integrations

GET

/api/v1/proxies

List all proxy integrations for the authenticated user.

Parameters

Name	Type	Required	Description
include_inactive	`boolean`	Optional	Include disabled integrationsDefault: `false`
provider	`string`	Optional	Filter by provider ID

Request Example

curl -X GET "https://api.alterlab.io/api/v1/proxies?include_inactive=false" \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Response Example

{
  "integrations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Oxylabs Residential",
      "provider": "oxylabs",
      "is_active": true,
      "is_default": true,
      "success_rate": 98.5,
      "total_requests": 1250,
      ...
    }
  ],
  "total": 1
}

Test Integration

POST

/api/v1/proxies/{integration_id}/test

Test proxy integration connectivity by making a test request.

Parameters

Name	Type	Required	Description
integration_id	`uuid`	Required	Integration ID to test
test_url	`string`	Optional	URL to test againstDefault: `https://httpbin.org/ip`
timeout_seconds	`integer`	Optional	Request timeoutDefault: `30`

Request Example

curl -X POST https://api.alterlab.io/api/v1/proxies/550e8400.../test \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test_url": "https://httpbin.org/ip"}'

Response Example

{
  "success": true,
  "response_time_ms": 1234,
  "proxy_ip": "185.234.123.45",
  "proxy_country": "US",
  "error": null
}

Get Provider Usage

GET

/api/v1/proxies/{integration_id}/usage

Get usage statistics from the proxy provider's API (bandwidth, requests, balance).

Parameters

Name	Type	Required	Description
integration_id	`uuid`	Required	Integration ID

Request Example

curl -X GET https://api.alterlab.io/api/v1/proxies/550e8400.../usage \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Response Example

{
  "bandwidth_used_bytes": 5368709120,
  "bandwidth_used_gb": 5.0,
  "bandwidth_limit_bytes": 107374182400,
  "bandwidth_limit_gb": 100.0,
  "bandwidth_percent_used": 5.0,
  "requests_made": 12500,
  "requests_limit": null,
  "balance_remaining": 95.50,
  "currency": "USD",
  "period_start": "2025-01-01T00:00:00Z",
  "period_end": "2025-01-31T23:59:59Z"
}

Set Default Integration

PUT

/api/v1/proxies/{integration_id}/default

Set an integration as the default for scraping requests. Only one integration can be default.

Parameters

Name	Type	Required	Description
integration_id	`uuid`	Required	Integration ID to set as default

Request Example

curl -X PUT https://api.alterlab.io/api/v1/proxies/550e8400.../default \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Response Example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Oxylabs Residential",
  "provider": "oxylabs",
  "is_default": true,
  ...
}

Delete Integration

DELETE

/api/v1/proxies/{integration_id}

Permanently delete a proxy integration. This cannot be undone.

Parameters

Name	Type	Required	Description
integration_id	`uuid`	Required	Integration ID to delete

Request Example

curl -X DELETE https://api.alterlab.io/api/v1/proxies/550e8400... \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Response Example

// 204 No Content on success

Best Practices

1. Use Multiple Providers

Different proxy providers have different IP pools and success rates on different sites. Configure multiple integrations and let AlterLab automatically select the best one.

// Set priority to control selection order
{
  "integrations": [
    {"name": "BrightData Residential", "priority": 10},  // First choice
    {"name": "Oxylabs Datacenter", "priority": 5},       // Fallback
    {"name": "SmartProxy", "priority": 1}                // Last resort
  ]
}

2. Monitor Usage & Balance

Check your provider usage regularly to avoid running out of bandwidth mid-scrape. Set up alerts in your provider's dashboard for low balance warnings.

Poll /proxies/{id}/usage weekly
Set budget alerts in provider dashboards
Configure fallback to AlterLab proxies when balance is low

3. Test Before Production

Always test new integrations with the /testendpoint before using them in production scraping jobs.

4. Rotate Credentials Periodically

For security, rotate your proxy credentials every few months. Update them in AlterLab using the credentials update endpoint.

Credential Security

Your proxy credentials are encrypted at rest using AES-256 encryption. AlterLab never logs or exposes your credentials. However, you should still use dedicated credentials for AlterLab rather than your main account credentials.

Integration Limits

Maximum integrations per user: 10 total
Maximum per provider: 3 integrations (for different zones/configs)
Validation timeout: 30 seconds
Endpoints cache: Refreshed on demand or every 24 hours

← Back to API Reference Next: Webhooks Guide →