Enterprise API

import alterlab

client = alterlab.Client(api_key="YOUR_API_KEY")

response = client.enterprise.bulk_submit(
    bulk_id="batch-2026-07-01-001",
    jobs=[
        # Scrape job
        {"url": "https://example.com/product/123"},
        # SERP search job with demographic targeting
        {
            "query": "best running shoes",
            "engine": "google",
            "country": "us",
            "session_pool_id": "profile-f-25-34-us",
            "safe_search": False,
        },
    ],
    rate_shape_config={
        "jobs_per_hour": 5000,
        "burst_limit": 50000,
        "priority": 3,
    },
)

print(response.bulk_id)           # "batch-2026-07-01-001"
print(response.job_count)         # 2
print(response.status)            # "accepted"
print(response.estimated_completion_at)

import time
import alterlab

client = alterlab.Client(api_key="YOUR_API_KEY")

# Poll until completed
while True:
    status = client.enterprise.bulk_status("batch-2026-07-01-001")
    print(f"{status.jobs_released}/{status.job_count} released, status={status.status}")
    if status.status in ("completed", "failed"):
        break
    time.sleep(30)

import alterlab

client = alterlab.Client(api_key="YOUR_API_KEY")

response = client.enterprise.create_profile(
    age_bucket="25-34",
    gender="F",
    geo="US",
    profile_id="profile-f-25-34-us",
    video_count=12,
    proxy_url="http://user:[email protected]:8080",
)

print(response.profile_id)  # "profile-f-25-34-us"
print(response.status)      # "building"
print(response.message)     # "Profile warmup started. Poll GET /api/v1/b2b/profiles/{profile_id}..."

import time
import alterlab

client = alterlab.Client(api_key="YOUR_API_KEY")

# Poll until complete (~15-18 minutes)
while True:
    profile = client.enterprise.get_profile("profile-f-25-34-us")
    print(f"Status: {profile.status}")
    if profile.status == "complete":
        print(f"Inferred: {profile.inferred_gender} / {profile.inferred_age_bucket}")
        print(f"Is inferred: {profile.is_inferred}")
        # Use in bulk jobs as session_pool_id
        break
    elif profile.status == "failed":
        print(f"Build failed: {profile.error}")
        break
    time.sleep(60)

import alterlab

client = alterlab.Client(api_key="YOUR_API_KEY")

result = client.enterprise.verify_profile(
    profile_id="profile-f-25-34-us",
    proxy_url="http://user:[email protected]:8080",
)

print(result.is_inferred)   # True
print(result.age_bucket)    # "25-34"
print(result.gender)        # "Female"
print(result.basis)         # "cookie"
print(result.message)       # Human-readable summary

import alterlab

client = alterlab.Client(api_key="YOUR_API_KEY")

response = client.enterprise.trigger_delivery(
    tenant_id="your-tenant-uuid",
    config_id="your-config-uuid",
    batch_id="pilot-batch-001",
    results=[
        {"job_id": "job-1", "query": "running shoes", "ads": [...]},
        {"job_id": "job-2", "query": "hiking boots", "ads": [...]},
    ],
)

print(response.method)         # "s3"
print(response.destination)    # "s3://your-bucket/prefix/pilot-batch-001.jsonl"
print(response.result_count)   # 2
print(response.bytes_written)  # 1024
print(response.signature)      # HMAC-SHA256 audit signature

import alterlab

client = alterlab.Client(api_key="YOUR_API_KEY")

# Poll for proxy outcome events (consume-on-read)
response = client.enterprise.proxy_feedback(limit=500)

for event in response.events:
    if event["status"] == "blocked":
        print(f"Job {event['job_id']} blocked: {event['block_reason']}")
        # Rotate proxy for this country
        rotate_proxy(event["country"])
    elif event["status"] == "success":
        print(f"Job {event['job_id']} succeeded via {event['session_pool_id']}")

print(f"Processed {response.count} events")