AGENT_DOCS.txt

SCRAPERCITY API REFERENCE - FOR AI AGENTS
==========================================

BASE: https://app.scrapercity.com
AUTH: Authorization: Bearer <api_key>
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