Overview

Standalone Exa people-search API wrapper with secret-key handling and rich public-profile output. This folder is a complete, standalone Apify Actor. Its layout intentionally follows the workspace’s jobright-scraper: source code lives under src/, platform definitions live under .actor/, the container is defined by Dockerfile, and the dataset can be checked with dataset-validator.js. It does not import code from another scraper folder, so it can be pushed, built, scheduled, or versioned independently.

The live extraction path is Exa’s official Search API with category: people. Live runs require exaApiKey (or EXA_API_KEY). Credentials are sent only in the relevant request header. The Actor never prints them, stores them in the dataset, or writes them to diagnostics.

Extraction design

The Actor prefers structured public data. It normalizes source records into a stable job/profile contract and also retains every upstream field inside rawData. Null and undefined source values are removed recursively. Normalized fields use empty strings, empty arrays, or empty objects when an optional value is not published, so dataset records contain no JSON null values. This is deliberate: an empty value means “not supplied by the source,” not an invented fact.

For job records, the output can include identifiers, title, company, all locations, salary range and unit, employment type, workplace mode, dates, description text and HTML, responsibilities, requirements, benefits, skills, taxonomy, education, language, visa information, application links, recruiter data, organization enrichment, funding, classifications, and structured geocoding. Source-specific fields that do not have a normalized column remain available in rawData.

Inputs

The full machine-readable input contract is in .actor/input_schema.json. Every Actor defaults to a maximum of ten results and enforces a minimum request of ten. Depending on this source, useful fields include search terms, location, time window, start URLs, concurrency, richer-description toggles, and secret credentials. Advanced filters are passed only as documented primitive query parameters; the Actor does not execute arbitrary code from input.

Local development and verification

Install dependencies and run a ten-record smoke test:

npm install
apify run --purge --input '{"sampleMode":true,"maxItems":10}'
npm run validate:data

A source-live example is:

apify run --purge --input '{"exaApiKey":"<secret>","query":"Senior software engineers in Berlin","maxItems":10}'
npm run validate:data

The optional sampleMode uses real public GitHub profile records as a credential-free structural smoke test. The records are labelled public_structural_smoke; they are not represented as Exa results.

After each run, inspect storage/datasets/default for records and storage/key_value_stores/default/RUN_SUMMARY.json for machine-readable status. SOURCE_METADATA records the provider, source counts, and mode. A failure creates a sanitized ERROR_DIAGNOSTIC; it never creates fake fallback jobs or silently converts an access error into no_results.

Production behavior

Push this folder as its own Actor with apify push. Configure secrets in Apify’s encrypted input or environment settings, not in source files. The output schema exposes direct links to the dataset, run summary, and diagnostic store. Deduplication uses a stable source ID or canonical URL. HTTP requests use bounded timeouts and limited retry with backoff for temporary network or rate-limit failures.

The Actor reads public job or profile information only. Availability and field completeness depend on what the upstream source publishes at run time. Empty optional fields are preserved honestly; values are never guessed. Respect the source’s terms, applicable privacy rules, API plan limits, and retention requirements when scheduling or redistributing output.

Source identity

• Standalone actor: exa-ai-people-search
• Original catalog reference ID: uf4Y3fzLfSWsnHsn5
• Provider mode: exa
• Source/platform: Exa.ai
• Record type: person
• Default output request: 10

Keyless Exa mode (2026-10-21)

The default dataSource: "mcp" performs a fresh people search through Exa's official public MCP service at https://mcp.exa.ai/mcp, documented at https://exa.ai/mcp. It needs no API key and returns up to 20 public LinkedIn professional profiles. The service's free usage and availability limits apply; rate limits fail explicitly without evasion or sample fallback.

Results are live queries of Exa's search index, not direct LinkedIn recrawls or independently verified employment claims. dataMode is live_exa_index, extractionStatus is indexed_profile, and source timestamps and endpoint are retained. Missing fields remain empty. Query and location influence retrieval; they are not guaranteed exact filters. No private contact details are requested.

For keyed /search features choose dataSource: "api" and supply your own Exa key. API-only search type/highlight controls do not apply to MCP mode. includeText and maxCharacters control the returned text in both modes. Sample mode is rejected. Older API instructions below apply to API mode only.