People Search Reference

Overview

Endpoint: POST https://api.exa.ai/search with "category": "people" What it searches: 1B+ public professional profiles aggregated from LinkedIn, company pages, and other sources. Index refreshed weekly. Semantic search over structured attributes (role, skill, company, location, seniority). Natural language queries return relevance-ranked people results via API. For creating lists or enriching over many people at scale, use Websets.

Minimal Working Example

curl -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{"query": "senior ML engineers at fintech companies", "category": "people", "contents": {"highlights": true}}'

from exa_py import Exa
exa = Exa()
result = exa.search("senior ML engineers at fintech companies", category="people", contents={"highlights": True})

import Exa from "exa-js";
const exa = new Exa();
const result = await exa.search("senior ML engineers at fintech companies", { category: "people", contents: { highlights: true } });

Parameter Restrictions

The people category does not support the following parameters. Using them returns a 400 error:

Unsupported Parameter	Workaround
`startPublishedDate`	Not available. People profiles don’t have publish dates.
`endPublishedDate`	Not available.
`excludeDomains`	Not available.
`includeDomains`	Not available.

Supported Parameters

Parameter	Type	Notes
`query`	string	Natural language. Supports role, skill, company, location, seniority.
`category`	string	Must be `"people"`.
`type`	string	`"auto"` recommended. `"deep"` and `"deep-reasoning"` also work.
`numResults`	integer	1–100. Default 10.
`contents`	object	`text`, `highlights`, `summary`, all nested under `contents`.

Structured Entity Metadata

People Search returns structured person metadata in entities for result rows that resolve to a person. Each person entity has type: "person", a stable id, a schema version, and a properties object with person profile fields.

{
  "title": "Jane Doe - VP Engineering",
  "url": "https://www.linkedin.com/in/janedoe",
  "entities": [
    {
      "id": "person_...",
      "type": "person",
      "version": 1,
      "properties": {
        "name": "Jane Doe",
        "firstName": "Jane",
        "lastName": "Doe",
        "location": "San Francisco, California, United States",
        "workHistory": [
          {
            "title": "VP Engineering",
            "location": "San Francisco, California, United States",
            "dates": { "from": "2022-01-01", "to": null },
            "company": { "id": "company_...", "name": "Example AI" }
          }
        ],
        "educationHistory": [
          {
            "degree": "BS Computer Science",
            "dates": { "from": "2010", "to": "2014" },
            "institution": { "id": null, "name": "Stanford University" }
          }
        ]
      }
    }
  ]
}

Field	Type	Notes
`entities[].id`	string	Stable person entity identifier.
`entities[].type`	string	`"person"`.
`entities[].version`	integer	Entity schema version.
`properties.name`	string \| null	Full name.
`properties.firstName`	string \| null	First name.
`properties.lastName`	string \| null	Last name.
`properties.location`	string \| null	Person location.
`properties.workHistory`	array	Known roles. Each item has `title`, `location`, `dates`, and `company`.
`properties.workHistory[].dates`	object \| null	`{ "from": string \| null, "to": string \| null }`. `to: null` usually means current when the source represents an active role.
`properties.workHistory[].company`	object \| null	Referenced company: `{ "id": string \| null, "name": string \| null }`.
`properties.educationHistory`	array	Known education entries. Each item has `degree`, `dates`, and `institution`.
`properties.educationHistory[].institution`	object \| null	Referenced institution: `{ "id": string \| null, "name": string \| null }`.

Top-level property keys are present on person entities. Treat individual values and nested fields defensively because profile sources can vary in the information they include.

Query Patterns

By role and company:

"product managers at Microsoft"
"enterprise sales reps from Salesforce in EMEA"

By skill set:

"machine learning engineer with PyTorch experience"
"full-stack developer React and Node.js"

By seniority and location:

"VP Engineering AI infrastructure San Francisco"
"CTO at fintech startups in New York"

Composite:

"senior data scientists at Series B healthcare companies in Boston"
"DevOps engineers with Kubernetes experience at Fortune 500 companies"

Common Mistakes

Wrong	Correct
`excludeDomains: [...]` with `category: "people"`	Remove `excludeDomains`. Not supported for people. Returns 400.
`startPublishedDate: "2025-01-01"` with `category: "people"`	Remove date filters. Not supported for people. Returns 400.
Missing `category: "people"`	Without `category`, the search runs against the general web index, not the people index. Always include `"category": "people"`.

Patterns and Gotchas

Always set category: "people". Without it, you search the general web index and won’t get structured people results.
Use highlights for agent workflows. People profiles are dense. Highlights extract the most relevant career details without flooding your context window.
Use entities for typed metadata. Read names, locations, work history, and education history from results[].entities[].properties; use text or highlights for supporting snippets.
Natural language is the only filter. Since date filters, text filters, and domain filters aren’t supported, encode all constraints in your query string.
Python SDK uses snake_case. numResults → num_results, maxCharacters → max_characters.
Combine with deep search for custom enrichment. Use type: "deep" with outputSchema when you need fields outside the built-in person entity schema.

API

Data

MCP

SDKs

Integrations

Admin

Additional Resources

People Search Reference

Overview

Minimal Working Example

Parameter Restrictions

Supported Parameters

Structured Entity Metadata

Query Patterns

Common Mistakes

Patterns and Gotchas

​Overview

​Minimal Working Example

​Parameter Restrictions

​Supported Parameters

​Structured Entity Metadata

​Query Patterns

​Common Mistakes

​Patterns and Gotchas

Overview

Minimal Working Example

Parameter Restrictions

Supported Parameters

Structured Entity Metadata

Query Patterns

Common Mistakes

Patterns and Gotchas