# StepStone Scraper — Jobs DE/AT/BE/NL, Salaries & Monitor (MCP) (`amygraphics/stepstone-jobs-scraper`) Actor

StepStone jobs in Germany, Austria, Belgium & the Netherlands: title, company, salary (exact and estimated), benefits + full descriptions. Monitor mode: new jobs, salary updates & filled ads. $0.60 per 1 000 jobs.

- **URL**: https://apify.com/amygraphics/stepstone-jobs-scraper.md
- **Developed by:** [Zakaria el bouami](https://apify.com/amygraphics) (community)
- **Categories:** Jobs, Lead generation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## StepStone Job Scraper — Germany, Austria, Belgium & the Netherlands (MCP)

Scrape **StepStone**, the #1 job board in Germany, for keyword or URL searches: one clean row per
job posting, with salary data, company info and a built-in **monitor mode** for new jobs, salary
updates and filled ads. No browser, no login, no account.

**Find → Compare → Monitor → Alert.**

| What you get | Why it matters |
|---|---|
| **Salary** — exact when the employer published one, plus StepStone's **predicted range** (`salaryMin` / `salaryMax`, yearly, currency) and a readable `salaryText` | Salary benchmarking without opening a single page |
| **Company** — name, company id, profile URL, logo | Recruiting leads and market maps |
| **Full details** (`includeDetails`) — complete job description, employment type, industry, direct-apply flag, hiring-organisation address, coordinates when published | Everything you need for AI matching or job-board mirroring |
| Freshness — `datePosted`, `daysSincePosted`, publish window, and StepStone's own **“posted within 24 h / 7 days”** filter | Cheap daily incremental runs |
| Rich extras — benefits list, skills, home-office flag, paid-placement flags (`isSponsored`, `isTopJob`), result section (main / regional / semantic) | Ranking and filtering that most scrapers miss |
| **Monitor mode** — `new`, `updated`, `salary_updated`, `closed` (filled or expired) | Job-market intelligence on autopilot |

### Hard problems this Actor solves

1. **The bot wall — solved with residential IPs + a real cookie session.** StepStone sits behind
   Akamai: from datacenter IPs the search pages simply **hang** (verified: the same request that
   times out from a datacenter IP returns the full page in ~5 s through a residential IP). This
   Actor therefore primes a cookie session (VISITOR_ID / `_abck` / `bm_sz` …) against StepStone's
   own homepage **through an Apify Residential proxy by default**, keeps one sticky IP per run,
   throttles politely (~1 request/second) and rotates the IP + re-primes the session automatically
   when StepStone starts blocking. It falls back to your own `proxyConfiguration`, then to Apify
   Proxy “auto”, then to a direct connection (with a warning).
   *Note: residential proxy traffic is billed by Apify to the account running the Actor — a
   1 000-job run typically transfers a few hundred MB.*
2. **Pagination that goes deep — and never silently loops.** Verified `?page=N` paging
   (25 jobs/page), using StepStone's own `pageCount`, with repeat-page detection and honest
   truncation reporting when a search is too broad.
3. **Filters that actually work** — taken from StepStone's own filter payload, not guessed:
   `postedWithin` (`24h` / `7d`), `minSalary` (EUR/year), `radiusKm`, `workFromHome`,
   `contractType`, `experience`, `discipline` and sorting by date or relevance.
4. **Honest monitoring.** History lives in an Apify key-value store, one per search scope.
   `closed` is only emitted when the scan was complete and error-free — never on a failed or
   truncated run.

### Quick examples

- **All new data-engineer jobs around Berlin** — `keyword: data engineer`, `location: berlin`,
  sort `date`, `postedWithin: 24h`.
- **Nursing jobs in Austria** — `country: at`, `keyword: pflegekraft`, `location: wien`.
- **Warehouse jobs in the Netherlands** — `country: nl`, `keyword: warehouse`, `location: amsterdam`.
- **Belgian jobs** — `country: be` (StepStone Belgium serves one shared pool through its
  Dutch-language interface; French-language postings appear in it too).
- **Daily alert** — `mode: monitor` on a schedule: only new jobs, salary updates and closed ads
  are returned (and billed).
- **Your own search** — paste any StepStone search URL in `searchUrl` and its filters are reused
  (handy for StepStone URL variants and for the Belgian/French interface if you have one).

### Inputs that matter

- `country`: `de`, `at`, `be` (Dutch interface), `nl` — France is **not** covered: `stepstone.fr` is
  a corporate site without job listings, and StepStone has no French job board.
- `keyword` + `location` (city or region, accents fine: “München”, “Düsseldorf”).
- `postedWithin`, `minSalary`, `radiusKm`, `workFromHome`, `sort`.
- `maxPages` (25 jobs per page) and `maxResults` (global cap — also the billing cap).
- `includeDetails` for full descriptions (one extra request per job).
- `mode: monitor` + `stateKey` (optional) for delta runs.

### Automation, MCP & scheduling

- **Schedule** it daily in Apify; monitor mode returns (and charges) only the deltas.
- **Integrations**: Google Sheets, Airtable, Slack, n8n, Zapier or your own API — one click.
- **MCP-ready for AI agents** — exposed through Apify's Model Context Protocol server as
  `amygraphics/stepstone-jobs-scraper`, so agents (Claude, Cursor, VS Code, custom agents) can
  find it, run it and pay autonomously (this Actor is whitelisted for agentic payments).

```json
{
  "mcpServers": {
    "apify": { "url": "https://mcp.apify.com?tools=amygraphics/stepstone-jobs-scraper" }
  }
}
```

Ask it things like:

- *"Find all new nursing jobs in Vienna posted in the last 24 hours, with salary estimates."*
- *"Every data-engineer job around Berlin — company, salary range and the full description."*
- *"Watch these search results and tell me each morning which jobs are new, which raised their salary, and which are gone."*

### Pricing

Pay-per-event: **$0.001** start + **$0.0006 per job** (`job-extracted`) — **$0.60 per 1 000 jobs**
(monitor mode only charges for new, changed and closed jobs). On top of that, Apify bills the
platform usage of the run, including the residential proxy traffic this site requires
(a 1 000-job run with `includeDetails` transfers more — leave descriptions off if you only need
the listings).

### Fair use

Only publicly visible search results are fetched, without login, at a polite rate (≈1 request per
second, exponential backoff, no parallel hammering). StepStone's `robots.txt` asks crawlers to keep
out of deep query-string URLs; this Actor behaves like a careful reader rather than a search-engine
crawler: it never touches `/public-api/`, `/listing/`, `/search-results/` or any logged-in area, and
it throttles. Use the data responsibly and respect StepStone's terms and your local privacy law
(GDPR) when you contact companies.

***

### Deutsch (kurz)

**StepStone Scraper für Deutschland, Österreich, Belgien und die Niederlande**: Keyword- oder
URL-Suche, eine saubere Zeile pro Stellenanzeige — Titel, Firma, **Gehalt** (exakt oder geschätzt),
Benefits, Homeoffice-Flag und mit `includeDetails` die **komplette Stellenbeschreibung**.
**Monitor-Modus**: nur neue Jobs, Gehaltsänderungen und abgelaufene Anzeigen. Filter, die wirklich
funktionieren: „innerhalb 24 h / 7 Tage“, Mindestgehalt, Umkreis, Sortierung nach Datum.
25 Jobs pro Seite, automatische Erkennung von Seiten-Wiederholungen. **0,60 $ pro 1 000 Jobs.**

### Français (bref)

**StepStone** pour l'Allemagne, l'Autriche, la Belgique (NL/FR) et les Pays-Bas : recherche par
mots-clés ou par URL, une ligne propre par offre — titre, entreprise, **salaire** (exact ou estimé),
avantages, télétravail, et la **description complète** avec `includeDetails`. Mode **monitor** :
uniquement les nouvelles offres, changements de salaire et annonces retirées. La France n'est pas
couverte (`stepstone.fr` n'a pas d'offres). **0,60 $ pour 1 000 offres.**

# Actor input Schema

## `mode` (type: `string`):

search = extract every matching job. monitor = compare with the previous run and only return what is new, changed (salary updates included) or gone — perfect for a daily schedule.

## `country` (type: `string`):

Which StepStone site to search. France is not covered: stepstone.fr is a corporate site with no job listings.

## `keyword` (type: `string`):

Job title / keywords, e.g. "data engineer", "pflegekraft", "warehouse".

## `location` (type: `string`):

Optional city or region, e.g. Berlin, München, Wien, Amsterdam. Combined with Radius (km) below.

## `searchUrl` (type: `string`):

Instead of keyword/location, paste any StepStone search-result URL — its filters (radius, age, salary, …) are reused.

## `radiusKm` (type: `integer`):

Search radius around the location. StepStone default is 30.

## `postedWithin` (type: `string`):

Only jobs published recently — StepStone's own freshness filter (perfect for cheap daily runs).

## `minSalary` (type: `integer`):

Optional salary floor, e.g. 50000. Uses StepStone's salary filter (works where the site offers it).

## `workFromHome` (type: `string`):

Optional. StepStone's own code: 1 = home-office possible, 2 = partially home-office. Leave empty for any.

## `contractType` (type: `string`):

Advanced, optional. Example codes from the German site: 222 = Feste Anstellung (permanent contract).

## `experience` (type: `string`):

Advanced, optional. Example codes: 90002 = with professional experience, 90001 = entry level.

## `discipline` (type: `string`):

Advanced, optional. Example: IT — matches StepStone's discipline facet value.

## `sort` (type: `string`):

date = newest postings first (recommended, required for cheap incremental runs). relevance = StepStone's default ranking.

## `maxPages` (type: `integer`):

Each page holds 25 jobs. 10 pages = up to 250 jobs. The Actor stops earlier when the results end.

## `maxResults` (type: `integer`):

Global cap on rows returned (and billed).

## `includeDetails` (type: `boolean`):

One extra request per job: adds the full description, employment type, industry, direct-apply flag and the hiring organisation's address.

## `onlyChanges` (type: `boolean`):

In monitor mode, return only the deltas instead of the full list (unchanged jobs are not billed).

## `detectClosed` (type: `boolean`):

Flag jobs that disappeared from the search results as closed (filled or expired). Only done when the scan was complete and error-free.

## `stateKey` (type: `string`):

Optional name for this monitored search. Leave empty — it is derived from the search scope.

## `delayMs` (type: `integer`):

Politeness delay. Leave 0 for the built-in value (~1.1 s between search pages) — do not lower it, StepStone blocks fast crawlers.

## `proxyConfiguration` (type: `object`):

Optional — leave EMPTY. StepStone's Akamai layer hangs datacenter requests, so the Actor already uses Apify's Residential proxy by default (billed to your account as platform usage). Set this only if you want a specific proxy setup.

## Actor input object example

```json
{
  "mode": "search",
  "country": "de",
  "keyword": "data engineer",
  "location": "berlin",
  "searchUrl": "",
  "radiusKm": 30,
  "postedWithin": "",
  "workFromHome": "",
  "contractType": "",
  "experience": "",
  "discipline": "",
  "sort": "date",
  "maxPages": 1,
  "maxResults": 5,
  "includeDetails": false,
  "onlyChanges": true,
  "detectClosed": true,
  "stateKey": "",
  "delayMs": 0
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "search",
    "country": "de",
    "keyword": "data engineer",
    "location": "berlin",
    "radiusKm": 30,
    "postedWithin": "",
    "workFromHome": "",
    "sort": "date",
    "maxPages": 1,
    "maxResults": 5,
    "includeDetails": false,
    "onlyChanges": true,
    "detectClosed": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("amygraphics/stepstone-jobs-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "search",
    "country": "de",
    "keyword": "data engineer",
    "location": "berlin",
    "radiusKm": 30,
    "postedWithin": "",
    "workFromHome": "",
    "sort": "date",
    "maxPages": 1,
    "maxResults": 5,
    "includeDetails": False,
    "onlyChanges": True,
    "detectClosed": True,
}

# Run the Actor and wait for it to finish
run = client.actor("amygraphics/stepstone-jobs-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "search",
  "country": "de",
  "keyword": "data engineer",
  "location": "berlin",
  "radiusKm": 30,
  "postedWithin": "",
  "workFromHome": "",
  "sort": "date",
  "maxPages": 1,
  "maxResults": 5,
  "includeDetails": false,
  "onlyChanges": true,
  "detectClosed": true
}' |
apify call amygraphics/stepstone-jobs-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,amygraphics/stepstone-jobs-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/upAXK4r7EjKTyhbci/builds/XL6W7N25G9vPqmKMR/openapi.json