Skip to main content

​
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: YOUR_API_KEY" \
  -d '{"query": "senior ML engineers at fintech companies", "category": "people", "contents": {"highlights": true}}'

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

import Exa from "exa-js";
const exa = new Exa("YOUR_API_KEY");
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 ParameterWorkaround
startPublishedDateNot available. People profiles don’t have publish dates.
endPublishedDateNot available.
excludeDomainsNot available.
includeDomainsNot available.

​
Supported Parameters

ParameterTypeNotes
querystringNatural language. Supports role, skill, company, location, seniority.
categorystringMust be "people".
typestring"auto" recommended. "deep" and "deep-reasoning" also work.
numResultsinteger1–100. Default 10.
contentsobjecttext, 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" }
          }
        ]
      }
    }
  ]
}
FieldTypeNotes
entities[].idstringStable person entity identifier.
entities[].typestring"person".
entities[].versionintegerEntity schema version.
properties.namestring | nullFull name.
properties.firstNamestring | nullFirst name.
properties.lastNamestring | nullLast name.
properties.locationstring | nullPerson location.
properties.workHistoryarrayKnown roles. Each item has title, location, dates, and company.
properties.workHistory[].datesobject | null{ "from": string | null, "to": string | null }. to: null usually means current when the source represents an active role.
properties.workHistory[].companyobject | nullReferenced company: { "id": string | null, "name": string | null }.
properties.educationHistoryarrayKnown education entries. Each item has degree, dates, and institution.
properties.educationHistory[].institutionobject | nullReferenced 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

WrongCorrect
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.