# JOIN Jobs Search Scraper (`jobsapi/join-jobs-search-scraper`) Actor

Extract public job postings from Join.com company career pages with title, locations, description HTML, public dates, and source URLs.

- **URL**: https://apify.com/jobsapi/join-jobs-search-scraper.md
- **Developed by:** [Jobs API](https://apify.com/jobsapi) (community)
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.99 / 1,000 join job records

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## JOIN Jobs Search Scraper

This Actor collects source-grounded job and employer information published on public JOIN company career pages and public JOIN job pages. It reads the page's public `__NEXT_DATA__` payload; it does not use an authenticated account, private API, proxy, cookies, browser fingerprint changes, or CAPTCHA/security-challenge workarounds.

### Input

`startUrls` accepts one to twenty HTTPS URLs on `join.com` (or `www.join.com`) in one of these forms:

- `https://join.com/companies/{company}`
- `https://join.com/companies/{company}/{job}`

If omitted, the Actor uses the public JOIN company page `https://join.com/companies/join`. An explicitly supplied invalid URL is rejected; it is not silently replaced with the default.

`includeDetails` defaults to `true` and fetches the public job detail pages needed for full descriptions and job attributes. The dataset contract requires a successful detail response and at least 21 distinct meaningful source fields, so `includeDetails: false` intentionally emits no listing-only rows. `maxItems` (1–100, default 20) limits emitted jobs across all input URLs. `maxPages` (1–10, default 3) bounds listing pages per company URL. `requestTimeoutSeconds` (5–120, default 30) and `maxResponseBytes` (100,000–5,000,000, default 5,000,000) bound each ordinary public request.

Example:

```json
{
  "startUrls": [{ "url": "https://join.com/companies/join" }],
  "includeDetails": true,
  "maxItems": 20,
  "maxPages": 3
}
```

### Dataset

Each dataset item is a complete, detail-verified job record—not a listing fallback or a run diagnostic. A row is emitted only after a successful 2xx detail response and when it contains at least 21 distinct meaningful populated source-field paths. Identifiers, URLs, aliases, repeated description renderings, raw source snapshots, and run metadata do not count toward this threshold. Where the source publishes them, records retain the job title and status, dates, employer identity and description, industry and employee range, offices, mission, benefits and values, structured location and remote/hybrid terms, work schedule and language, employment and contract types, category, salary range/currency/frequency, and readable source-authored description sections. Optional facts are omitted when JOIN does not publish them; fields are not filled with guesses.

Diagnostics and request receipts are stored in KVS (`RUN_DIAGNOSTICS` and `REQUEST_RECEIPTS`), never as dataset rows. `OUTPUT_SUMMARY.status` is the platform process status (`SUCCEEDED` or `FAILED`); `resultStatus` separately reports `COMPLETE`, `LIMITED`, `SKIPPED`, `DEFERRED`, `NO_DATA`, or `FAILED`. A handled source barrier (HTTP 401/403/429/451 or visible source-authored denial/challenge) discards every buffered row and returns `SUCCEEDED` / `SKIPPED`. A generic transport failure is `DEFERRED`, not proof of a block; if complete rows were already stored, they are preserved as `SUCCEEDED` / `LIMITED`. Likewise, a later dataset-write or finalization error cannot relabel previously stored rows as failed. A fatal zero-row run calls the Actor failure lifecycle and reports `FAILED` / `FAILED`; a clean run without eligible job rows reports `SUCCEEDED` / `NO_DATA`. No diagnostic or placeholder item is added to the dataset. The Actor does not retry blocked requests or change identities, cookies, proxies, or fingerprints. For ordinary navigation only, it follows at most one site-authored redirect when the destination remains on an allowed JOIN `/companies/{same-company}` page or job path; both hops are retained as receipts. This handles JOIN's public canonical job links and is never used after a block or challenge.

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

### Local checks

From this directory, run `npm test`, `npm run check`, `npm run lint`, and `apify validate-schema`. Dataset validation is read-only. Do not run an Actor just to validate an existing store; when an Actor run is explicitly in scope, choose a fresh actor-relative storage directory, preserve all existing stores, and use `--resurrect` (never `--purge`):

```powershell
$env:APIFY_LOCAL_STORAGE_DIR = "storage-join-validation-unique"
if (Test-Path -LiteralPath $env:APIFY_LOCAL_STORAGE_DIR) { throw "Choose a new storage directory." }
apify run --resurrect --input-file .actor/input.json
npm run validate:dataset -- storage-join-validation-unique
```

The dataset validator reads generated output only; it does not create or edit dataset records.

# Actor input Schema

## `startUrls` (type: `array`):

Public Join.com company career pages or individual public job pages. URLs must use HTTPS on join.com and stay under /companies/.

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

Fetch each public job page for description HTML and detailed metadata.

## `maxItems` (type: `integer`):

Maximum job records to emit across all supplied company pages.

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

Maximum public pagination pages to request per company.

## `requestTimeoutSeconds` (type: `integer`):

Timeout applied to each ordinary public page request.

## `maxResponseBytes` (type: `integer`):

Safety limit for each public page response.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://join.com/companies/join"
    }
  ],
  "includeDetails": true,
  "maxItems": 20,
  "maxPages": 3,
  "requestTimeoutSeconds": 30,
  "maxResponseBytes": 5000000
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `datasetUi` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `diagnostics` (type: `string`):

No description

## `receipts` (type: `string`):

No description

## `health` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("jobsapi/join-jobs-search-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("jobsapi/join-jobs-search-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 '{}' |
apify call jobsapi/join-jobs-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jobsapi/join-jobs-search-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/5xA1YioWM6Kb47xeP/builds/i1OkM11MNM1Cs7BwF/openapi.json
