StepStone Jobs Scraper — a field manual, one chapter per mode

StepStone is geo-sensitive and sits behind Akamai, so most tools stall on its search pages. This Actor reads StepStone's own result-list data request-only, with Chrome TLS impersonation over residential proxies (Germany by default). It runs four ways, and the mode you pick decides everything else.

This manual is organized the same way the Actor is: one chapter per mode. Read the chapter that matches what you have — a keyword, a URL, or a specific job page — and skip the rest.

Covers StepStone Germany (.de), Austria (.at), France (.fr), and Denmark (.dk / best effort) · HTTP-only, no login, no browser · CSV / Excel / JSON / API.

Chapter	mode	Start from	You provide
1	SEARCH	keyword + location	keywords, location, country
2	URLS	StepStone links	startUrls (search or job pages)
3	DETAILS	exact job pages	startUrls (direct job URLs)
4	AUTO	whatever you have	any of the above — it decides

Not sure which chapter is yours? Start from what's in your hand:

What you have                                mode
 ─────────────                                ────
 🔎 a keyword + a place ────────────────────▶ SEARCH   build + paginate search URLs
 🔗 StepStone links you already collected ──▶ URLS     search pages paginate, job pages read
 📄 exact job-page URLs, full detail ───────▶ DETAILS  whole page + JSON-LD (+contacts)
 🧭 a mix / not sure ───────────────────────▶ AUTO     inspects each input, routes it

---

🔎 Chapter 1 — SEARCH: build searches from a keyword and place

Give it a role and a location and it constructs the StepStone search URL for the country you choose, follows pagination up to maxPagesPerSearch, and returns one flat row per job. This is the mode for "find me every data engineer job in Berlin."

Input:

{
  "mode": "SEARCH",
  "keywords": ["software developer"],
  "location": "berlin",
  "country": "DE",
  "postedWithin": "14d",
  "maxItems": 10,
  "maxPagesPerSearch": 1
}

What comes back — one job row (compact):

{
  "id": "123456789",
  "title": "Senior Software Developer (m/w/d)",
  "companyName": "Example GmbH",
  "location": "Berlin",
  "postCode": "10115",
  "datePosted": "2026-08-01T00:00:00Z",
  "workModel": "hybrid",
  "section": "organic",
  "labels": ["Full-time", "Permanent"],
  "skills": ["Python", "AWS"],
  "salary": "65.000 € - 80.000 €",
  "salaryMin": 65000,
  "salaryMax": 80000,
  "salaryCurrency": "EUR",
  "salaryPeriod": "YEAR",
  "jobUrl": "https://www.stepstone.de/stellenangebote--...",
  "sourceUrl": "https://www.stepstone.de/jobs/software-developer/in-berlin",
  "country": "DE",
  "searchKeyword": "software developer",
  "scrapedAt": "2026-08-07T10:30:02Z"
}

Pass several keywords and they each run as their own search. postedWithin accepts all · 1d · 3d · 7d · 14d, applied while building the URL or after parsing.

---

🔗 Chapter 2 — URLS: crawl StepStone links you already have

Already sitting on StepStone search-result pages or a stack of job links? Paste them into startUrls and this mode crawls each one — search pages get paginated, job pages get read directly. It's the mode for reproducing a filtered search you built by hand in the browser.

Input:

{
  "mode": "URLS",
  "startUrls": [
    { "url": "https://www.stepstone.de/jobs/ai?searchOrigin=Homepage_top-search" },
    { "url": "https://www.stepstone.de/jobs/data-engineer/in-berlin" }
  ],
  "maxItems": 50,
  "maxPagesPerSearch": 3
}

Every row records where it came from: sourceUrl (the page it was found on), jobUrl / relativeUrl (the listing itself), and page · positionOnPage · positionAbsolute for exactly where it ranked. Listing flags travel too — isAnonymous, isSponsored, isTopJob, isHighlighted, plus section (organic, recommended, …).

---

📄 Chapter 3 — DETAILS: read specific job pages, in full

When you already have the precise job URLs and want the whole page — not a result-list snippet — DETAILS fetches each one and returns the rich record. This is the mode for enriching a shortlist.

Input:

{
  "mode": "DETAILS",
  "startUrls": [
    { "url": "https://www.stepstone.de/stellenangebote--Senior-Software-Developer--123456789" }
  ],
  "includeDetails": true,
  "includeContacts": true
}

What includeDetails: true adds (fetched and merged from each job page):

Field	Meaning
descriptionText · description	Clean text plus original HTML
detailTitle	Title from the job page itself
employmentType	Full-time, part-time, etc.
validThrough · datePostedDetail	Posting window from JSON-LD
directApply	Whether direct apply is offered
hiringOrganization · jobLocationDetail · baseSalary	Structured JSON-LD blocks
detailUrl · detailFetched	Source URL and fetch flag

What includeContacts: true adds — public contact data scraped from the job text (it auto-enables detail fetching):

Field	Meaning
contacts.emails	Public email addresses on the page
contacts.phones	Public phone numbers, validated by surrounding context
contacts.people	Named contact persons with name and role
contacts.snippets	The surrounding text for each match

Many listings publish none of this — those rows simply omit the values.

---

🧭 Chapter 4 — AUTO: let it decide

The default. AUTO looks at what you passed and routes for you: keywords → behaves like SEARCH, startUrls → behaves like URLS/DETAILS depending on whether each link is a search or a job page. Mix keyword searches and pasted URLs in one run and it sorts them out — everything lands in the same dataset.

Input:

{
  "mode": "AUTO",
  "keywords": ["product manager"],
  "location": "munich",
  "startUrls": [
    { "url": "https://www.stepstone.de/jobs/data-engineer/in-berlin" }
  ],
  "maxItems": 25
}

Provide at least one of keywords or startUrls and AUTO handles the rest.

---

🌍 Coverage: DACH, France, and Denmark

country switches the domain used for generated keyword searches:

Value	Domain	Notes
DE	stepstone.de	Germany (default)
AT	stepstone.at	Austria
FR	stepstone.fr	France
DK	stepstone.dk	Denmark — best effort

Because StepStone is geo-sensitive, the proxy defaults to residential Germany; change apifyProxyCountry in proxyConfiguration to match your target market.

---

🎛️ Cross-cutting knobs (work in every chapter)

🎯 Filters — postedWithin (age), remoteOnly (keep remote-flagged jobs), salaryOnly (keep only jobs with salary text or structured salary), excludeRecommended (drop recommended padding StepStone adds to thin pages — on by default).

💶 Work model & salary — every job is normalized to workModel = onsite / hybrid / remote, and salary is parsed into salary · salaryMin · salaryMax · salaryCurrency · salaryPeriod · salaryAvailable · salaryType when StepStone exposes it.

Output shape — outputMode: compact (clean normalized fields, default) or full (more native StepStone fields); rawOutput: true attaches the raw object under _raw for custom pipelines.

⚡ Performance — the fixed 1 GB runtime processes result rows, detail pages, and contact enrichment concurrently. maxConcurrency controls the parallel pipeline; maxRetries and maxProxyRetries default to 4 with short capped backoff, while requestDelayMs stays at 0 for the fastest normal runs.

Every completed run writes an OUTPUT summary with saved, issues, durationSeconds, and a small errorSamples list. Empty valid inputs return NO_INPUT without contacting StepStone or producing a failed run; malformed field types are rejected by Apify before the Actor starts.

The Overview dataset tab gives a quick scan of every run: Job ID, Title, Company, Location, Work model, Salary (+ min/max), Posted date, Section, and clickable Job / Source URLs.

---

💬 Quick answers

• Login or cookies? No — request-only, impersonating a Chrome TLS fingerprint over Apify Proxy.
• Why are some salary fields empty? StepStone only publishes salary on some listings; use salaryOnly: true to keep only those.
• Why does contact data come back empty sometimes? Many job pages have no public emails/phones/people. Empty means "not present," not "not looked for."
• How do I keep exports clean? Leave outputMode on compact; only reach for full / rawOutput when troubleshooting.

⭐ Got clean StepStone data out of a run? Leaving a rating on the Apify Store is the best way to support the Actor and shape where it goes next.

🏷️ Tags: stepstone · stepstone scraper · jobs scraper · job listings · recruiting · salary data · lead generation · germany jobs · hiring intelligence