> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automindz.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Scrape Stepstone jobs
> Search Stepstone and extract structured German job listings with full descriptions
Searches [Stepstone](https://www.stepstone.de/) 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](/api-reference/endpoint/scrape-arbeitsagentur-jobs) (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](/api-reference/endpoint/get-stepstone-jobs-status).
**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:
| Field | Values | Keeps |
| - | - | - |
| `work_type` | `full-time`, `part-time` | jobs with that time model |
| `posted_within_days` | `1`, `7` | jobs posted in the last day or week (the only two windows Stepstone offers) |
| `work_from_home` | `partial`, `only` | jobs offering some home office, or fully remote ones |
| `job_language` | `de`, `en` | listings written in that language |
| `application_method` | `company-website`, `quick-apply` | jobs that apply off-site, or Stepstone one-click applications |
| `discipline` | `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` | jobs in that broad field (Stepstone's own taxonomy) |
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](/api-reference/endpoint/get-stepstone-jobs-status) with that id to retrieve the results.
```json theme={null}
{
"request_id": "run_stepstone_abc123",
"status": "QUEUED"
}
```
## OpenAPI
````yaml openapi.json POST /v1/scrape-stepstone-jobs/async
openapi: 3.1.0
info:
title: Automindz API
version: 0.1.0
servers:
- url: https://api.automindz.co
description: Production
security: []
paths:
/v1/scrape-stepstone-jobs/async:
post:
tags:
- scrape-stepstone-jobs
summary: Scrape Stepstone Jobs
operationId: scrape_stepstone_jobs_v1_scrape_stepstone_jobs_async_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StepstoneJobsRequest'
example:
title: Python Entwickler
location: Berlin
radius: 30
rows: 25
posted_within_days: 7
work_from_home: partial
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StepstoneJobsResponse'
example:
request_id: run_stepstone_abc123
status: QUEUED
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
StepstoneJobsRequest:
properties:
title:
type: string
title: Title
description: >-
Job title or keyword to search (required). Stepstone's search is
path-based (`/jobs/`), so there is no location-only search.
location:
anyOf:
- type: string
- type: 'null'
title: Location
description: >-
City, region or postcode to search around (e.g. `Berlin`). Omit to
search all of Germany.
radius:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Radius
description: >-
Search radius in kilometres around `location`. Ignored when no
location is given.
rows:
type: integer
multipleOf: 25
maximum: 100
minimum: 25
title: Rows
description: >-
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.
default: 25
start_page:
type: integer
minimum: 1
title: Start Page
description: >-
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).
default: 1
work_type:
anyOf:
- type: string
enum:
- full-time
- part-time
- type: 'null'
title: Work Type
description: >-
Employment time model. Stepstone expresses this as a path segment
rather than a filter, so it changes the search URL itself.
posted_within_days:
anyOf:
- type: integer
enum:
- 1
- 7
- type: 'null'
title: Posted Within Days
description: >-
Only jobs posted within the last 1 or 7 days. Stepstone offers
exactly these two windows — no other value exists on the site.
work_from_home:
anyOf:
- type: string
enum:
- partial
- only
- type: 'null'
title: Work From Home
description: >-
`partial` keeps jobs offering some home office, `only` keeps fully
remote ones.
job_language:
anyOf:
- type: string
enum:
- de
- en
- type: 'null'
title: Job Language
description: Language the listing is written in, as Stepstone detects it.
application_method:
anyOf:
- type: string
enum:
- company-website
- quick-apply
- type: 'null'
title: Application Method
description: >-
`company-website` keeps jobs that apply off-site, `quick-apply`
keeps Stepstone's one-click applications.
discipline:
anyOf:
- type: string
enum:
- 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
- type: 'null'
title: Discipline
description: >-
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.
include_details:
type: boolean
title: Include Details
description: >-
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.
default: true
type: object
required:
- title
title: StepstoneJobsRequest
StepstoneJobsResponse:
properties:
request_id:
type: string
title: Request Id
status:
type: string
title: Status
default: QUEUED
type: object
required:
- request_id
title: StepstoneJobsResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.