> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Search recent remote LinkedIn jobs and save traceable results

> Search one page of recent remote LinkedIn jobs with linkedin.web_v2.search_jobs, archive the response with save_jobs.py and export a reviewed jobs.csv.

To build a shortlist of recent remote LinkedIn jobs, request one page with `linkedin.web_v2.search_jobs`, archive the response with `save_jobs.py`, and export a filterable `jobs.csv` with `export_jobs.py` after you confirm the field mapping in `mapping.json`. Request skills or the hiring team with `linkedin.web_v2.get_job_detail` only for the jobs you select. The workflow reads jobs; the workflow does not apply to jobs or contact anyone.

## 1. Set scope and cost

The example reads one page of worldwide remote software-engineering jobs and saves the response as evidence. Check `data:linkedin.web_v2.search_jobs` at the free /v1/capabilities/inspect endpoint for the current inputs and price. Each additional page and each detail call is a separate paid query.

## 2. Send explicit filters

```bash
curl --fail-with-body -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"linkedin.web_v2.search_jobs","params":{"keywords":"software engineer","geo_code":92000000,"date_posted":"Past week","onsite_remotes":["Remote"],"sort_by":"Most recent","start":0}}' \
  -o linkedin-jobs-page-0.json
```

`geo_code=92000000` is worldwide. A city needs the city's integer region code, not a city-name string. See [filter details](/faq/linkedin-job-filters).

For a Remote-or-Hybrid search, do not put two values in `onsite_remotes`: only the first value takes effect. Send the [two separate request examples](/faq/linkedin-job-filters), keep each request's query provenance, and budget for both calls. `title_ids` and `functions` appear in the accepted input shape but do not filter results.

## 3. Validate and archive the response

On HTTP failure, keep the error and do not export. Save the script below as `save_jobs.py`. `save_jobs.py` checks the business status and `data` before creating a new file; the script does not guess list paths and never overwrites an earlier archive.

```python
import json, pathlib, sys
source, target = map(pathlib.Path, sys.argv[1:3])
r = json.loads(source.read_text(encoding="utf-8"))
if r.get("status") != "succeeded" or r.get("action") != "linkedin.web_v2.search_jobs":
    raise ValueError("Expected successful LinkedIn job search")
if "data" not in r or r["data"] is None:
    raise ValueError("Missing query data")
record = {"request_id": r.get("request_id"), "action": r["action"], "data": r["data"]}
with target.open("x", encoding="utf-8") as f:
    json.dump(record, f, ensure_ascii=False, indent=2)
print(str(target))
```

```bash
python3 save_jobs.py linkedin-jobs-page-0.json linkedin-jobs-verified-0.json
```

`linkedin-jobs-verified-0.json` keeps `request_id`, `action` and the complete `data` for review and later field mapping. The archive is the raw result, not a normalized job CSV: BeatAPI sanitizes and passes `data` through directly without a uniform `jobs[]` field.

## 4. Page within a budget and deduplicate

If further pages are approved, keep the filters, change `start` to 25 and then 50, and save each page under a new filename. Compare each new page with the previous page, and stop on repetition or failure. Deduplicate by the actual job URL or stable ID, not by title, because different companies can use the same title. Record the retrieval time and filters; one page does not represent every available job.

## 5. Retrieve only selected details

Take the full job URL of a selected job from the results and call `linkedin.web_v2.get_job_detail`. Set `include_skills=true` for skills or `include_hiring_team=true` for the hiring team. Do not request details for every result by default, and do not use returned contact information for outreach automatically.

## 6. Verify and recover

Confirm that `linkedin-jobs-verified-0.json` is readable, keeps `request_id` and matches your filters. A business failure creates no archive, and `save_jobs.py` never overwrites an existing archive, so a repeated conversion needs a new destination or reuses the saved file. Keep the source JSON for diagnosis; fix local conversion errors from the saved JSON instead of repeating the paid query.

[Profile and company URLs](/faq/linkedin-profile-and-posts)

## 7. Deliver a filterable job table through an explicit reviewed mapping

The raw JSON archive is not the final shortlist. Deliver `jobs.csv` with title, company, location, work mode, publication time, job URL, shortlist decision, reason, `request_id` and source filename. Leave the decision and reason columns blank for the reader to fill in.

Confirm the field mapping against one actual listing before exporting the page. Each row needs a job title, company and listing URL. If a search result includes a location but omits the work mode or publication date, leave the work-mode and publication-date cells blank and check the listing during review.

Open the original `linkedin-jobs-page-0.json` and inspect one actual job object. Check the object's title, company and job link against the original listing. In `mapping.json`, `rows` is a JSON Pointer to the job array, and `fields` maps column names to paths within each job object. Pointers begin with `/`, array indices use `/0`, and `~` and `/` in keys are escaped as `~0` and `~1`. `title`, `company` and `url` are required. Set `location`, `work_mode` and `published_at` to null when unavailable; the search filters do not establish the work mode of every returned job.

The example below shows mapping-file syntax only; the `YOUR_*` paths are placeholders, not BeatAPI response keys. Replace every `YOUR_*` with a path you reviewed:

```json
{"rows":"/data/YOUR_JOB_ARRAY","fields":{"title":"/YOUR_TITLE","company":"/YOUR_COMPANY","url":"/YOUR_JOB_URL","location":null,"work_mode":null,"published_at":null}}
```

Save the script below as `export_jobs.py`. `export_jobs.py` validates the entire collection before opening the destination file. Bad mappings, missing required values, nested objects where scalar values belong and non-job URLs make the script fail. The script deduplicates by job URL path, keeps identical titles that have different URLs, neutralizes spreadsheet formulas and refuses to overwrite an earlier table.

```python
import csv, json, pathlib, sys
from urllib.parse import urlparse
source, mapping, target = map(pathlib.Path, sys.argv[1:4])
r = json.loads(source.read_text(encoding="utf-8"))
m = json.loads(mapping.read_text(encoding="utf-8"))
if r.get("status") != "succeeded" or r.get("action") != "linkedin.web_v2.search_jobs":
    raise ValueError("Expected original successful job-search response")
def pointer(value, path):
    if path == "": return value
    if not isinstance(path, str) or not path.startswith("/"):
        raise ValueError("Use JSON Pointer paths")
    for part in path[1:].split("/"):
        part = part.replace("~1", "/").replace("~0", "~")
        value = value[int(part)] if isinstance(value, list) else value[part]
    return value
items = pointer(r, m["rows"])
if not isinstance(items, list): raise ValueError("Mapped rows is not an array")
fields = m["fields"]
for name in ["title", "company", "url"]:
    if name not in fields: raise ValueError("Map title, company and url explicitly")
rows, seen = [], set()
for item in items:
    row = {}
    for name in ["title", "company", "url", "location", "work_mode", "published_at"]:
        path = fields.get(name)
        value = pointer(item, path) if path is not None else None
        if value is not None and not isinstance(value, (str, int, float)):
            raise ValueError("Mapped values must be scalar: " + name)
        row[name] = "" if value is None else str(value)
    if any(not row[k].strip() for k in ["title", "company", "url"]):
        raise ValueError("Missing required job evidence")
    url = urlparse(row["url"])
    if url.scheme != "https" or url.hostname not in ["linkedin.com","www.linkedin.com"] or not url.path.startswith("/jobs/view/"):
        raise ValueError("Expected a LinkedIn job URL")
    key = url.path.rstrip("/")
    if key in seen: continue
    seen.add(key)
    row.update(request_id=r.get("request_id",""), source_file=source.name,
               shortlist="", reason="")
    rows.append(row)
def safe(value):
    text = str(value)
    return "'" + text if text.lstrip().startswith(("=","+","-","@")) else text
columns = ["title","company","location","work_mode","published_at","url",
           "shortlist","reason","request_id","source_file"]
with target.open("x",encoding="utf-8-sig",newline="") as f:
    writer=csv.DictWriter(f,fieldnames=columns);writer.writeheader()
    writer.writerows({k:safe(row[k]) for k in columns} for row in rows)
print(json.dumps({"exported_rows":len(rows),"source_rows":len(items)}))
```

```bash
python3 export_jobs.py linkedin-jobs-page-0.json mapping.json jobs.csv
```

In your spreadsheet, filter by company, location or work mode, open the job URLs and fill in the shortlist and reason columns. Compare at least two rows against the original job objects. An empty result produces a header row only, which does not mean no company is hiring. Check `exported_rows` against the deduplicated records. Keep `mapping.json` and the source response, so a corrected mapping can be re-exported without another paid query. The export does not apply to jobs, contact recruiters, estimate salaries or fill in unavailable information.