ScraperCity logo

Signals API Documentation

Signals

Find companies showing a buying signal right now. type "ads": companies running ads on Meta (Facebook and Instagram), Google, LinkedIn and TikTok, found by keyword and location or checked from your own list of websites. type "hiring": companies hiring for a role on LinkedIn Jobs and Indeed. One row per company with its website, the signal (platforms and ad links, or the job and its link) and a decision maker contact from the Lead Database where one matches. Set replaceContacts to swap contacts who have left for the person in that role now before the file is delivered.

$0.0094 per company running ads, $0.0009 per website per platform checked, $0.0043 per company hiring; minimum charge per searchPOST /api/v1/scrape/signals

Parameters

NameTypeRequiredDescription
typestringRequiredads (companies running ads) or hiring (companies hiring for a role)Example: ads
keywordstringOptionaltype ads: find advertisers for this keyword (send keyword OR domains)Example: roofing
domainsstring[]Optionaltype ads: check these websites instead (send keyword OR domains). Every website gets a row, with running_ads_on empty when no ads were found. Charged for each platform that answers for each website; a website no platform answered for shows as not checked and costs nothing.Example: ["acmeroofing.com", "brightsmiledental.com"]
platformsstring[]Optionaltype ads: any of meta, google, linkedin, tiktok (default: all). TikTok publishes ads for EU countries, the UK, Switzerland and Turkey only, and is searched by keyword only.Default: ["meta","google","linkedin","tiktok"]Example: ["meta", "google"]
jobTitlestringOptionaltype hiring: the role companies are hiring for (required for hiring)Example: Sales Development Representative
postedWithinstringOptionaltype hiring: 24h, 7d or 30dDefault: 7dExample: 7d
sourcesstring[]Optionaltype hiring: job boards, linkedin and/or indeed (default: both)Default: ["linkedin","indeed"]Example: ["linkedin", "indeed"]
includeAgenciesbooleanOptionaltype hiring: keep staffing and recruiting agenciesDefault: falseExample: false
locationstringOptionalCity, state or region (ads: added to the keyword search; hiring: where the jobs are)Example: Denver
countrystringOptionalTwo-letter country codeDefault: USExample: US
maxCompaniesnumberOptionalThe most companies to return (default 200 for ads by keyword, 500 for hiring)Example: 200
replaceContactsbooleanOptionalReplace contacts who have left with the person in that role now, before the file is delivered. Unlimited and free on the $649 plan, otherwise $0.02 per contact replaced.Default: falseExample: true

Examples

Find local businesses running ads

curl -X POST https://app.scrapercity.com/api/v1/scrape/signals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ads",
    "keyword": "roofing",
    "location": "Denver",
    "platforms": ["meta", "google"],
    "maxCompanies": 100
  }'

Check which platforms your prospects advertise on

curl -X POST https://app.scrapercity.com/api/v1/scrape/signals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ads",
    "domains": ["acmeroofing.com", "brightsmiledental.com"]
  }'

Companies hiring SDRs this week, with fresh contacts

curl -X POST https://app.scrapercity.com/api/v1/scrape/signals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hiring",
    "jobTitle": "Sales Development Representative",
    "postedWithin": "7d",
    "maxCompanies": 500,
    "replaceContacts": true
  }'

Check status and download

curl -X GET https://app.scrapercity.com/api/v1/scrape/status/{runId} \
  -H "Authorization: Bearer YOUR_API_KEY"

# When status is SUCCEEDED, download the CSV
curl -L https://app.scrapercity.com/api/downloads/{runId} -o signals.csv

Use Cases

  • •Find local businesses that spend on Google or Facebook ads (agencies, marketing services)
  • •See which platforms your prospects and competitors advertise on
  • •Sell to companies the moment they hire for the role your product helps
  • •Recruiting and staffing outreach to companies with open roles
  • •Find growing companies by the roles they are adding

Best Practices

  • •Running ads means: Meta active ads, Google ads shown in the last 30 days, LinkedIn ads from the last 30 days, TikTok active ads
  • •Keyword searches on Meta and Google usually finish in under a minute, and a website list check on them takes about 2 minutes per 100 websites; searches that include LinkedIn or TikTok take 5-15 minutes, and hiring searches 2-10 minutes
  • •Ads: use one keyword per search and add a city or state for local businesses
  • •Ads CSV columns: company_name, domain, running_ads_on, platforms_count, ad counts, dates and ad library links per platform, sample_ad_landing_page and contact_* columns
  • •Hiring CSV columns: company_name, domain, company_linkedin_url, company_size, industry, open_jobs, job_title, job_url, job_location, posted_at, source, other_job_titles and contact_* columns

Every scrape returns a runId. Poll GET /api/v1/scrape/status/{runId} until it completes, then download via GET /api/downloads/{runId}?format=csv.

Authenticate every request with Authorization: Bearer YOUR_API_KEY. See the full API reference for authentication, rate limits and error codes.