SCRAPERCITY API REFERENCE — FOR AI AGENTS ========================================== BASE: https://app.scrapercity.com AUTH: Authorization: Bearer ALL RESPONSES: JSON PATTERN: POST start → GET status → GET download PRICING: Plans $49, $149, $649/mo. Each gives wallet credits. Scrapers deduct per-lead. ──────────────────────────────────────── SCRAPE ENDPOINTS (POST /api/v1/scrape/{slug}) ──────────────────────────────────────── apollo Body: { url: "https://app.apollo.io/#/people?...", count: 1000, fileName: "My Export" } Returns: { runId, message } Cost: $0.0039/lead | Min 500, max 50000 DELIVERY: UP TO 4 DAYS. Use webhook, not polling. apollo-filters Body: { seniorityLevel, functionDept, companyIndustry, personCountry, personState, companyCountry, companyState, companySize, personTitles:[], companyDomains:[], companyKeywords:[], personCities:[], companyCities:[], hasPhone, count, fileName } At least one filter required. Returns: { runId, message } Cost: $0.0039/lead | DELIVERY: UP TO 4 DAYS. maps Body: { searchStringsArray: ["plumbers"], locationQuery: "Denver, CO", maxCrawledPlacesPerSearch: 500 } Returns: { runId, datasetId, priceMicro } Cost: $0.01/place | Delivery: 5-30 min email-validator Body: { emails: ["user@example.com", "test@company.com"] } Returns: { runId, emailCount, estimatedCost } Cost: $0.0036/email | Delivery: 1-10 min email-finder Body: { contacts: [{ first_name: "John", last_name: "Doe", domain: "acme.com" }], autoValidateEmails: false, autoFindMobiles: false } Returns: { runId, contactCount, priceMicro } Cost: $0.05/contact | Delivery: 1-10 min mobile-finder Body: { inputs: ["linkedin.com/in/johndoe", "jane@company.com"] } Returns: { runId, inputCount, priceMicro } Cost: $0.25/input | Delivery: 1-5 min people-finder Body: { name: ["John Doe"], email: [], phone_number: [], street_citystatezip: [], max_results: 1 } Returns: { runId, totalSearches, estimatedCost } Cost: $0.02/result | Delivery: 2-10 min store-leads Body: { platform: "shopify", countryCode: "US", totalLeads: 1000, emails: true, phones: true, category: "", city: "" } Returns: { runId, totalLeads, estimatedCost } Cost: $0.0039/lead | Delivery: INSTANT (cached DB) builtwith Body: { technology: "Shopify", fileName: "Shopify sites" } Returns: { runId, technology, estimatedCost } Cost: $4.99 flat | Delivery: 1-5 min criminal-records Body: { name: "John Smith", state: "CA", dob: "02/07/1992" } state and dob optional. Returns: { runId, name, state } Cost: $1.00 only if records found | Delivery: 2-5 min airbnb-email Body: { mode: "city", city: ["Miami, FL"], maxResults: 100 } Modes: "city" (search cities), "single" (one listing URL), "bulk" (multiple listing URLs) For single: { mode: "single", listingUrl: "https://airbnb.com/rooms/..." } Optional: checkin, checkout, maxPages, onlyProHosts, onlyUniqueEmails Returns: { runId } Cost: $0.0001/listing | Delivery: 10-30 min youtube-email Body: { channels: ["@MrBeast", "https://youtube.com/@Channel"] } Accepts @handles or full YouTube URLs. Returns: { runId } Cost: per channel | Delivery: 5-15 min website-finder Body: { domains: ["acme.com", "example.com"], jobTitle: "CEO" } jobTitle is optional. Domains without https prefix. Returns: { runId } Cost: per domain | Delivery: 5-15 min yelp-scraper Body: { searchTerms: ["plumbers"], locations: ["Denver, CO"], searchLimit: 10 } OR: { directUrls: ["https://yelp.com/biz/..."] } Returns: { runId } Cost: $0.01/listing | Delivery: 5-15 min angi-angies-list-scraper Body: { keyword: "plumbers", zipCodes: ["80202", "80203"], maxItems: 100 } Returns: { runId } Cost: $0.01/listing | Delivery: 5-15 min zillow-agents Body: { location: "Denver, CO", specialty: "buyer", language: "English", searchLimit: 10 } specialty and language optional. Returns: { runId } Cost: per agent | Delivery: 5-15 min bizbuysell-scraper Body: { startUrls: ["https://bizbuysell.com/..."], maxItems: 100 } Pass BizBuySell search result URLs. Returns: { runId } Cost: $0.01/listing | Delivery: 5-15 min crexi-scraper Body: { startUrls: ["https://crexi.com/..."] } Pass Crexi search result URLs. Returns: { runId } Cost: $0.029/listing | Delivery: 5-15 min property-lookup Body: { addresses: ["123 Main St, Denver, CO 80202"], includeOwnerContact: false } Full address with city, state, zip required. Returns: { runId } Cost: $0.15/address | Delivery: 2-10 min ──────────────────────────────────────── STATUS & DOWNLOAD ──────────────────────────────────────── GET /api/v1/scrape/status/{runId} Returns: { status, statusMessage, handled, requested, outputUrl } Status values: RUNNING | SUCCEEDED | FAILED | CANCELLED When SUCCEEDED: outputUrl = "/api/downloads/{runId}" GET /api/downloads/{runId} Returns: CSV file (binary stream) Only available when status = SUCCEEDED POST /api/v1/scrape/cancel/{runId} Cancel a running job. GET /api/v1/scrape/logs/{runId} View run logs. ──────────────────────────────────────── ACCOUNT ──────────────────────────────────────── GET /api/v1/wallet Returns: { email, wallet: { balance_dollars, total_balance_dollars }, plan: { name, usage_percent }, billing: { next_billing_date } } GET /api/v1/runs?hours=24&limit=50 Returns: { runs: [{ run_id, status, handled, url, file_name, created_at }] } GET /api/v1/apollo-status Returns: { useApify, message } — check if Apollo URL endpoint is available ──────────────────────────────────────── DATABASES (GET, $649 plan only, 100k/day) ──────────────────────────────────────── GET /api/v1/database/leads?title=CTO&country=United States&hasEmail=true&page=1&limit=100 Filters: title, industry, country, state, city, companyName, companyDomain, companySize, seniority, department, hasEmail, hasPhone, minEmployees, maxEmployees Array params use repeated keys: ?seniority=vp&seniority=director Returns: { data: [...leads], pagination: { page, limit, total, totalPages } } GET /api/v1/database/local-businesses?... GET /api/v1/database/ecommerce?... Same pattern, different datasets. ──────────────────────────────────────── ERROR CODES ──────────────────────────────────────── 401 = Invalid/missing API key 402 = Insufficient balance (check wallet first!) 403 = Account cancelled or charge processing 409 = Duplicate request (same search within 2 min) 429 = Rate limited / duplicate within 30s 503 = Service temporarily unavailable ──────────────────────────────────────── WORKFLOW EXAMPLES ──────────────────────────────────────── 1. MAPS SCRAPE (fast): POST /api/v1/scrape/maps → get runId → poll status every 15s → download CSV 2. APOLLO SCRAPE (slow): POST /api/v1/scrape/apollo → get runId → configure webhook → wait for callback Do NOT poll Apollo in a tight loop. Check once per hour at most. 3. ENRICH PIPELINE: Apollo/Maps → download CSV → extract emails → POST email-validator → download validated CSV 4. LEAD DATABASE (instant): GET /api/v1/database/leads?title=CTO&industry=computer+software&hasEmail=true&page=1 Loop pages until page > totalPages 5. LOCAL BUSINESS PIPELINE: Yelp/Angi/Maps → download CSV → POST email-finder with names+domains → POST mobile-finder 6. REAL ESTATE PIPELINE: Zillow Agents + Property Lookup → download CSVs → enrich with email-finder