Skip to main content
POST
Scrape Stepstone Jobs
Searches Stepstone by job title and location and returns structured job listings — title, company, location, job type, posting date, and the full job description. Stepstone is Germany’s largest commercial job board. Together with Arbeitsagentur (the federal board) it covers both sides of the German market: Arbeitsagentur carries the public listings and recruiter contacts, Stepstone the commercial ones. The pipeline runs asynchronously. Use the returned request_id to poll for results.
Timing guidance: Most searches finish within a couple of minutes. Fetching each job’s full description (include_details, on by default) adds time per job. Poll every 15–30 seconds.

How it works

  1. Builds the Stepstone search from title, plus optional location, radius (kilometres) and any of the filters below
  2. Walks the search pages (25 listings per page, taken whole) up to rows, de-duplicating by listing. Stepstone pads a result page with adjacent suggestions; only the jobs that actually match the search are returned, and total_found counts those
  3. When include_details is true (default), fetches each job’s page for the full description, the exact posting date and the employer’s postal address
  4. Returns structured job listings (search URLs, totals, and the jobs array)
title is required — Stepstone’s search is keyword-based, so there is no location-only search. radius only applies when a location is set.

Filters

All optional, and all mapped to Stepstone’s own search facets: A value Stepstone has no facet for is rejected with a 422 rather than ignored, so a filter never silently fails to apply.
Salary can’t be filtered on. Stepstone shows salary only to signed-in users — the same reason salary_* comes back null on every job.
Salary is not available. Stepstone shows salary only to signed-in users, so salary_min, salary_max, salary_currency and salary_period are always null on Stepstone results. They are not omitted, so the shape stays the same as every other job source.
Scraping more than rows results. rows is a multiple of 25 (25, 50, 75 or 100) because Stepstone pages its results 25 at a time and pages are taken whole. Stepstone offers no result offset, so to harvest a larger search keep rows fixed and step start_page by rows / 25 across runs: with rows: 100, start_page: 1 → 5 → 9 … Stop when a run returns fewer than rows jobs — that’s the last page.

Response

The request is accepted immediately and returns a request_id — no jobs are returned here. Poll Get Stepstone job scrape status with that id to retrieve the results.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
title
string
required

Job title or keyword to search (required). Stepstone's search is path-based (/jobs/<title>), so there is no location-only search.

location
string | null

City, region or postcode to search around (e.g. Berlin). Omit to search all of Germany.

radius
integer | null

Search radius in kilometres around location. Ignored when no location is given.

Required range: x >= 1
rows
integer
default:25

Maximum number of jobs to scrape in this run (25, 50, 75 or 100; default 25). Stepstone lists 25 per page and pages are taken whole, so this must be a multiple of 25 — otherwise a partial last page would make start_page stepping skip listings.

Required range: 25 <= x <= 100Must be a multiple of 25
start_page
integer
default:1

Which Stepstone results page to start from (1-based). Stepstone has no result offset, only page numbers, so page through a search that has more matches than the rows cap by stepping start_page by rows / 25 across runs — e.g. rows: 100 with start_page: 1 returns jobs 1-100, start_page: 5 returns 101-200. Stop when a run returns fewer than rows jobs (that's the last page).

Required range: x >= 1
work_type
enum<string> | null

Employment time model. Stepstone expresses this as a path segment rather than a filter, so it changes the search URL itself.

Available options:
full-time,
part-time
posted_within_days
enum<integer> | null

Only jobs posted within the last 1 or 7 days. Stepstone offers exactly these two windows — no other value exists on the site.

Available options:
1,
7
work_from_home
enum<string> | null

partial keeps jobs offering some home office, only keeps fully remote ones.

Available options:
partial,
only
job_language
enum<string> | null

Language the listing is written in, as Stepstone detects it.

Available options:
de,
en
application_method
enum<string> | null

company-website keeps jobs that apply off-site, quick-apply keeps Stepstone's one-click applications.

Available options:
company-website,
quick-apply
discipline
enum<string> | null

Stepstone's own job-family filter, which narrows a generic keyword to one field. Validated rather than passed through because Stepstone answers an unrecognised discipline with zero results rather than an error, which would be indistinguishable from a search that simply matched nothing.

Available options:
accounting,
administration,
construction,
consulting,
customer-service,
design,
education,
engineering,
finance,
health,
hospitality,
hr,
insurance,
it,
law,
logistics,
management,
manufacturing,
marketing,
media,
retail,
sales,
science,
security,
skilled-trades,
social-services,
travel
include_details
boolean
default:true

Fetch each job's detail page for the full description, posting date and postal address (slower; one fetch per job). With this off, jobs carry the search-card teaser instead.

Response

Successful Response

request_id
string
required
status
string
default:QUEUED