scrapercity-lead-database

ScraperCity Lead Database

Overview

This skill turns "get me B2B leads for X" into a filter spec that returns the right people, a count check before anything is pulled, a paging plan that fits the 100,000 new leads a day allowance, and a short QA of the first 100 rows.

The Lead Database is included with the Growth plan ($149/mo) and up. Every lead returned is saved to the account. Only new leads count toward the daily allowance, and fetching a lead the account already has is free.

The mistakes it prevents:

• Pulling 20,000 rows on a filter that was wrong, because pagination.total and a 1-row sample were never checked first.
• Using country (where the person lives) when the user meant companyCountry (where the company is headquartered).
• Paging with page=2, 3, 4 while excludeDelivered=true, which skips records.
• Paying for an Apollo Scraper run and waiting 15 to 30 minutes for leads the database already returns in seconds.

When to Use

Use it when the user says:

• "Find VPs of Sales at 50-200 person SaaS companies in the US."
• "Pull every CFO in Texas at companies over $50M revenue."
• "Here is my people-search URL, get me these leads."
• "Set up a daily feed of new leads that match our ICP."
• "The database returned 503" or "409 filters_not_applied_yet" or "400 on my URL."
• "Should I use the Apollo Scraper or the Lead Database?"
• "Is this person still at that company?" (one socialUrl lookup)

Use a different skill for nearby jobs:

Prerequisites

• A ScraperCity account on Growth ($149/mo) or Scale ($649/mo). Starter does not include database access. Run check_wallet and read plan.name.
• An API key in SCRAPERCITY_API_KEY (MCP and CLI) or a Bearer header (REST).
• The ICP in words: titles, seniority, departments, industries, company size, revenue band, person or company geography, exclusions.
• The volume target and cadence: one-off (how many) or daily (how many new per day).

Authoritative Foundations

Details and routing: references/framework-notes.md.

Workflow

1. Confirm access and the job type

Call check_wallet. If the plan is Starter, stop and explain that the Lead Database needs Growth or Scale, and offer scrape_apollo as the pay-per-lead route. Classify the job:

2. Translate the ICP into filters

Map every ICP sentence to one filter. The full semantics are in references/filter-semantics.md. The rules that cause the most errors:

• Person vs company location. country, state, city are where the person is. companyCountry, companyState, companyCity are the company HQ. "US companies" means companyCountry. "People based in Texas" means state.
• Titles are partial match, comma separated. title: "VP Sales, Head of Sales" returns either. "CEO" also matches longer titles that contain it. Use notTitle to remove unwanted titles ("Assistant, Intern, Executive Assistant").
• Keywords are whole-word, any match. keywords: ["saas", "fintech"] returns companies tagged with either word. Use notKeywords to drop adjacent categories.
• Arrays are OR inside a filter, filters are AND across. seniority: ["vp","director"] plus industry: ["computer software"] means (VP or Director) and software.
• Countries take full names. "United States", "Germany". US, USA, UK and UAE also work.

If the user gave a people-search URL, pass it as url and read search_translation (step 4).

An ICP attribute with no filter (funding stage, technology, hiring, recent news) gets two routes, each written out as a call in the plan: the user's company list for that attribute, passed as companyDomain in comma-separated batches of about 200 domains, and a limit: 1 call with url set to a people-search URL that carries the attribute, whose search_translation shows whether it was applied. Tell the user how to build the URL. Never stand in a proxy (size band, keywords) for the attribute without labeling the list as the proxy. Add a column naming where the attribute came from (stage_source, tech_source).

3. Run a count check before pulling

Call with limit: 1. Read pagination.total and look at data[0]. Report the total to the user with the filter table. Decision rule:

A 503 here means the search ran too long: add a location or size band, or cut the title list, then retry.

4. Handle a people-search URL

Pass the URL as url. Any other filter you pass overrides the matching one from the URL. The response adds search_translation with three lists:

• applied: used as is.
• approximated: mapped to the closest database filter. Read each one and confirm with the user.
• not_supported: ignored. If a dropped filter defines the ICP (for example a technology filter), tell the user the count is broader than their URL.

A URL with nothing the database can use returns 400. Rebuild the search with explicit filters. A long URL or a long title list belongs in a POST body: the query string is refused past about 16KB, and the CLI switches to POST on its own past 6,000 characters.

5. Pull with the cursor

Send after: "0", limit: 100, then each response's pagination.next_after until it is null or the target count is reached. Use after for anything over a few pages. Use page only for small one-off reads without excludeDelivered.

6. Design the daily pull (feeds)

Each day: excludeDelivered: true, after: "0", limit: 100, loop next_after, stop at the daily target or when next_after is null. Starting from after=0 daily catches every lead the account does not own yet. Keep each day under 100,000 new leads (the allowance resets at midnight UTC per scrapercity.com/api-docs). Per the same page, the API takes 100 requests a minute per key, so 1,000 calls of 100 take at least 10 minutes. Write the run log: date, segment, new leads, last cursor.

7. QA the first page

Before the full pull, agree a sample size and pass mark with the user, open that many rows and check: title matches intent, company size inside the band, company HQ where expected, email present when hasEmail was set, no excluded titles leaking. Below the pass mark, fix the filter and re-run the count. The checklist is in references/troubleshooting.md.

8. Cut to the requested number and hand off

When the pull holds more rows than the user asked for, cut it the way references/scrapercity-agent-patterns.md section 6 sets out: dedupe on lowercased email, rank by the user's title order, cap per company domain (the user's cap, or one per role named), validate the top N, and top up from the ranked remainder for exactly the shortfall. Write each step as a script the user can run. Leave excludeDelivered off for a one-off list (re-fetching owned leads is free) and on for repeat pulls.

Send emails to validate_emails before any campaign, and route the file to cold-email-list. Never load an unvalidated pull into a sequencer.

ScraperCity Implementation

MCP (query_lead_database)

{
  "title": "VP Sales, Vice President of Sales, Head of Sales",
  "notTitle": "Assistant, Intern, Operations",
  "companyCountry": ["United States"],
  "minEmployees": 50,
  "maxEmployees": 200,
  "keywords": ["saas"],
  "hasEmail": true,
  "limit": 1
}

Then the same body with "limit": 100, "after": "0", looping on pagination.next_after.

CLI (db-leads)

npx scrapercity db-leads --title "VP Sales, Head of Sales" --not-title "Assistant, Intern" \
  --company-country "United States" --min-employees 50 --max-employees 200 \
  --keywords saas --has-email --limit 1

The CLI prints the total, the next cursor and the first 3 leads, so it is the fastest count check. For a full export, use REST or MCP. List flags (--industry, --country, --state, --seniority, --department, --company-country, --company-state, --not-industry) take commas.

REST

curl -s -G "https://app.scrapercity.com/api/v1/database/leads" \
  -H "Authorization: Bearer $SCRAPERCITY_API_KEY" \
  --data-urlencode "title=VP Sales, Head of Sales" \
  --data-urlencode "companyCountry=United States" \
  --data-urlencode "keywords=saas" --data-urlencode "notTitle=Assistant, Intern" \
  --data-urlencode "minEmployees=50" --data-urlencode "maxEmployees=200" \
  --data-urlencode "hasEmail=true" --data-urlencode "limit=100" --data-urlencode "after=0"

Arrays repeat the key (seniority=vp&seniority=director), so a GET with two seniorities sends the key twice. keywords and notKeywords also accept commas. POST /api/v1/database/leads with a JSON body takes the same parameters with arrays as JSON arrays.

Response fields to read

data[] (person fields plus company_industry, company_size, employees_count, company_website, company_annual_revenue, company_city, company_state, company_country, keywords), pagination (page, limit, total, totalPages, has_more, next_after), rate_limit, and search_translation when url was sent.

Lead Database or Apollo Scraper

Rule: on Growth or Scale, start with the database. Use scrape_apollo when the URL relies on filters listed in not_supported and the user needs them, or when the account is on Starter. A scrape_apollo response can include a lead_database block with matches (leads with the same filters in the database that the account does not have), a dashboard url and the api call that returns them now. Pull those first and size the Apollo run to the remainder.

Worked cost estimate

ICP: VP or Head of Sales, US-headquartered SaaS, 50-200 employees, email required. The count check returns 4,812.

The same 4,812 leads through scrape_apollo would cost 4,812 x $0.0039 = $18.77 plus the wait. On Growth the database costs nothing extra and finishes in minutes. The pull uses 4.8% of one day's 100,000 allowance. Show this table and get a go-ahead before the validation spend.

Output Format

A lead pull plan in Markdown, built from templates/output-template.md:

1. Request Summary: ICP in one paragraph, job type, plan confirmed.
2. Filter Spec: table of parameter, value, reason. Only parameter names the endpoint accepts.
3. Count Check: total from the limit: 1 call, sample row notes, search_translation lists if a URL was used.
4. Pull Plan: paging method, excludeDelivered, calls needed, days needed, daily new-lead count.
5. Cost and Allowance: table with $ figures and allowance share.
6. Sample QA: the sample check results against the pass mark set before the sample.
7. Next Steps: validation, segmenting, hand-off.

Run python3 scripts/check-output.py plan.md before sending.

• Each fact once; every call and script written out in full (no "..." values, no loop described in a comment); no counts or results marked assumed. If nothing has run, say so once at the top.
• What the reader receives is the deliverable only: no internal file paths, reference section numbers or runbook IDs; another skill is named only in a handoff line that tells the user what to run next; no tables of checks that were not run (one "Not checked:" line instead); and no repeated identical rows where one template plus a list will do.

Quality Check

• Every filter row uses a parameter that exists in query_lead_database.
• Person vs company location is stated for every geography filter.
• A count from a limit: 1 call is shown before any bulk pull.
• excludeDelivered: true is paired with after or page=1, never with page above 1.
• Daily new leads planned are at or below 100,000.
• Every approximated and not_supported item from search_translation is listed with what it means for the count.
• The cost table uses catalog prices and the paid total is shown and approved before any paid step.
• Sample QA done against a pass mark set before the sample, and the sample meets it.

Common Pitfalls

More failure modes and fixes: references/troubleshooting.md.

Execution Artifacts

Related Skills

• using-scrapercity-skills: router for every ScraperCity job.
• scrapercity-mcp, scrapercity-cli, scrapercity-api: access paths and setup.
• icp-list-builder and tam-builder: decide who to pull before you pull.
• decision-maker-finder: named-account people search.
• email-list-cleaner and cold-email-list: what happens to the file next.
• scrapercity-local-business-database: when the target is a local business, not a B2B role.