apify-jobs-data

Decide what the user wants done with the data — it changes only Step 6, not the shared core. Infer from the request; confirm if ambiguous:

• "what skills/salary/demand for X", "job-market for Y" → Market & salary analysis.
• "scrape / export / give me a dataset / CSV for a dashboard" → Structured export.
• "which of these fit my résumé", "rank these for me" → Résumé-fit (needs a résumé; anchor #7).
• Multiple are fine — e.g. analysis + export of the same run.

Ask these as one block before any Actor call. Defaults shown — always surface them so the user can override. (Anchor-block pattern from apify-verified-email-finder.)

1. Role / keywords — e.g. senior backend engineer. Required.
2. Location — city, country, or remote. Required. remote flips the remote-only filter on.
3. Boards — auto (default → aggregator, all boards the Actor supports for the country) or a named subset passed as the aggregator's platforms array (exact enum values from the live schema — e.g. LinkedIn, Indeed, Glassdoor; Google Jobs is not in the enum). Drives Step 2 and cost (Step 3).
4. Result cap — for the aggregator this is per platform (max_results: 25 ≈ 25 × the platforms hit — every platform the Actor supports for the country unless platforms is pinned), minimum 1. Start small (10–15 for a quick scan, 25–50 for analysis) and scale only if the sample is too thin — together with platforms it's the main cost lever, so budget max_results × platforms (Cost discipline, Step 3). Maps to each Actor's own field (max_results for the aggregator / maxItemsPerSearch for Indeed / maxItems for Glassdoor — actor-index.md).
5. Recency window — default 2 weeks. The aggregator takes this as a natural-language string ("2 weeks", "1 month"), not a day count.
6. Filters — optional constraints that drop a posting: salary_floor, remote_only, job_type (fulltime / contract / internship — no hyphen). Collect what the user volunteers.
7. Résumé / profile — only for résumé-fit mode: résumé text or a must-have + nice-to-have skill list. Without it, résumé-fit falls back to a mechanical score labeled Fit (partial).

Ambiguity rule: if role or location is missing or vague, ask one clarifying question before running. Never burn Actor compute on a guessed query.

Default to the aggregator — one run, 20+ boards (LinkedIn, Indeed, Glassdoor, ZipRecruiter, and more; not Google Jobs), country-aware routing, cheapest per-result. Every Actor here is pay-per-result — no subscriptions. The aggregator already covers LinkedIn cheaply, so there is no need for a per-board LinkedIn subscription Actor. If the user asks for Google Jobs specifically, say this skill does not cover it.

Start with the aggregator unless the user explicitly wants a single board. Named boards stay in one run: if the user names one or more boards, pass them in the aggregator's platforms array (anchor #3) — a single run whatever the number of boards, never one Actor per board. The only standalone route chosen up front is misceres/indeed-scraper, and only when the user wants Indeed exclusively.

Per-board fallback rule: after the run, count rows per requested board that match anchor #2 (location). A board the user named that comes back with zero (or near-zero) in-area rows — blocked, or the Actor ignored the location, as Indeed's path does — gets one fallback run with its standalone Actor from the table (misceres/indeed-scraper for Indeed, capped with maxItemsPerSearch), if budget and run count allow; its rows carry their own Source board and are deduped against the aggregator's in Step 5. Only if budget or the run count is gone do you report the board as a coverage gap instead — a board the user asked for is worth that one capped run. The fallback is conditional on a measured zero: outside it, never run two Actors against the same query. Never a second aggregator retry for the same board — whatever the cause (blocked, location ignored, or TIMED-OUT before the board was reached); do the per-board in-area count first, and if the aggregator timed out, narrow platforms/max_results only in the first run's design, never in a rerun. Full schemas and field mappings: reference/actor-index.md.

Map anchors → the chosen Actor's field names (per-Actor table in reference/actor-index.md). Aggregator example:

{ "keyword": "senior backend engineer", "location": "Berlin",
  "country": "Germany", "max_results": 50, "posted_since": "2 weeks", "remote_only": false }

Verified-from-live-schema notes for the aggregator: country is a full country name (Germany, United States), not an ISO-2 code; posted_since is a natural-language string ("2 weeks"), not a number of days; job_type is fulltime / parttime / contract / internship / all (no hyphen); and max_results is per platform — with platforms empty the actor fans out to every platform it supports for the country, so max_results: 50 can return several hundred rows; pin platforms to bound it. Other Actors use their own field names (actor-index.md).

Estimate before running. Formula and live rates in reference/gotchas.md. Guardrails:

• Estimated cost > $5 → warn with a rough number ("around $X").
• Estimated cost > $20 → require explicit confirmation before running.
• All routes are pay-per-result — cost scales with max_results × boards. Keep max_results modest to keep runs in the cents.

MCP path: call-actor with actor, input, callOptions {"timeout": 900, "memory": 2048}. It returns runId + datasetId. If status is RUNNING, poll get-actor-run (waitSecs ≤ 45) until SUCCEEDED. Capture both IDs for the run_metadata.json sidecar (and surface datasetId in export mode).

CLI path:

# Run options travel in --params: timeout 900 s (this skill's recommendation for the
# multi-board aggregator — same as the MCP callOptions above) paired with
# maxTotalChargeUsd = your Step 3 estimate (here the $5 warn threshold), the platform's
# cap on spend. `apify actors call` has no flag for maxTotalChargeUsd — use the API mode.
apify api POST "actors/agentx~all-jobs-scraper/runs" \
  --params '{"timeout":900,"maxTotalChargeUsd":5}' \
  --body '{"keyword":"senior backend engineer","location":"Berlin","country":"Germany","max_results":50,"posted_since":"2 weeks"}' \
  --user-agent apify-awesome-skills/apify-jobs-data 2>/dev/null
# the response returns immediately (data.id, data.defaultDatasetId); wait for the run:
apify api GET "actor-runs/RUN_ID" --params '{"waitForFinish":60}' \
  --user-agent apify-awesome-skills/apify-jobs-data 2>/dev/null   # repeat until data.status is SUCCEEDED
# then, using data.defaultDatasetId:
apify datasets get-items DATASET_ID --format json \
  --user-agent apify-awesome-skills/apify-jobs-data 2>/dev/null > /tmp/jobs.json

On the MCP path, pull with get-dataset-items (clean: true + a fields list). If the dataset exceeds the response cap, fetch directly: curl -H "Authorization: Bearer $APIFY_TOKEN" 'https://api.apify.com/v2/datasets/<id>/items?clean=true&fields=...' | jq — auth goes in the header, never as ?token= in the URL (it lands in access logs). On the CLI path prefer apify api GET "datasets/<id>/items" --params '{"clean":"true"}' --user-agent apify-awesome-skills/apify-jobs-data 2>/dev/null, which authenticates itself.

Report every failure explicitly (Actor, input, error) — never silently drop a board. If a board returns 0 in-area rows, apply the per-board fallback rule (Step 2) before concluding "no data". A board returning 0 while others return results is usually a block, not an empty market.

The shared core. Two parts:

1. De-noise — walk every row and remove the noise: location mismatches (the Actor's location filter is not trusted), duplicates/reposts across boards, hard-filter violations, off-target roles; flag (don't drop) ghost jobs, staffing-agency reposts, and bare-Remote rows with no stated region (remote: unverified — kept, but not counted as in-area). Skipped rows are kept in a separate Skipped section with a one-line reason — never silently dropped. Apply the location check first, then hard filters, then dedupe, so the funnel reads raw → after location check → after hard filters → after dedupe → clean. Full detection logic: reference/skip-pass.md.
2. Normalize — map each surviving row onto the consistent schema in reference/output-formats.md (title, company, location, remote flag, salary min/max/currency, seniority, skills, posted date, source board, apply URL). Field coverage varies by board — leave missing fields blank, never inferred.

Empty results are signal, not failure (from apify-easy-competitive-intelligence): 0 postings for a niche role in a small market is real information — report it, suggest widening recency or location, don't fabricate filler rows.

Run on the clean, normalized rows from Step 5.

• Market & salary analysis → compute the aggregations (demand, skills, salary distribution, remote mix) with coverage labels. Full method: reference/analysis.md.
• Structured export → write the normalized rows to CSV / JSON, and surface the raw Apify datasetId for direct ingestion. Schema and formats: reference/output-formats.md.
• Résumé-fit → a per-posting sub-agent reads each full JD against the résumé and returns fit, matched skills, gaps, the ATS keywords the résumé is missing, and a one-line hook — not keyword counting. Contract and rubric: reference/fit-scoring.md.

Whatever the mode, the remote: unverified rows from Step 5 travel with the output — not just their count: in any table, as their own group below the in-area rows (Remote — region unverified (K), same columns), never inside an "N in <city>" figure; in the CSV / JSON rows, with remote: unverified in flags. A number in the header alone is not delivery (reference/output-formats.md).

If the user picked more than one mode, produce each from the same run — no re-scrape.

Lead with a one-paragraph header: boards requested vs. boards that returned in-area rows (a missing board is a coverage gap — say so), the funnel (raw → after location check → after hard filters → after dedupe → clean, plus flagged ghost/agency counts and "N remote postings without a stated region" — reported separately, never inside the "in <city>" count; the N rows themselves follow the in-area rows as their own group, Step 6), date window, and the run cost. Then the mode output(s).

• Every statistic carries its coverage — e.g. "median salary €95k, from the 41% of postings that disclosed a figure". A number without coverage is misleading.
• Provenance — Source board(s) + apply URL per row; runId + datasetId in a run_metadata.json sidecar so any figure is re-verifiable.
• Synthesize for analysis/résumé-fit; write the full row set to the file. For export, the file (and dataset ID) is the deliverable.