> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# People Search

> Search for professionals, employees, and people using People Search in the Agent API

## Overview

The `people_search` tool enables models to find people and retrieve their professional information such as names, job titles, and companies. Use it to power workflows like lead research, recruiting pipelines, or organizational mapping.

Use it when your application needs to:

* Look up a specific person's professional background
* Find employees at a company by role or title
* Identify professionals in a particular field or location
* Research leadership teams or organizational structures

The model decides when to invoke `people_search` based on your prompt and instructions.

## Coverage

People Search can query public professional profiles and related professional context across several dimensions:

| Query by      | Example prompt                                                        |
| ------------- | --------------------------------------------------------------------- |
| **Name**      | "Find Sarah Chen and summarize her current professional role."        |
| **Role**      | "Find chief revenue officers at late-stage AI startups."              |
| **Company**   | "Find product leaders who work at Stripe."                            |
| **Education** | "Find Stanford alumni working in machine learning research."          |
| **Skill**     | "Find professionals with Kubernetes platform engineering experience." |
| **Location**  | "Find fintech compliance leaders in New York."                        |

<Warning>
  **Privacy and acceptable use:** Use People Search only for legitimate professional research workflows. Do not use it for harassment, doxxing, stalking, or unauthorized background screening. You are responsible for complying with applicable privacy, employment, and data protection laws, including GDPR and CCPA where they apply. The API returns publicly available professional information only.
</Warning>

### Query Tips

For the best results, guide the model with specific details in your prompt:

| Approach            | Example prompt                                  |
| ------------------- | ----------------------------------------------- |
| **Name + company**  | "Find John Smith who works at Google"           |
| **Role + company**  | "Who is the Head of Design at Figma?"           |
| **Role + location** | "Find marketing directors in San Francisco"     |
| **Role + field**    | "Find machine learning researchers at Stanford" |

<Info>
  The tool works best for people-related queries — it is not suited for general web search.
</Info>

## Tiered Configurations

The following four tiered configurations span the speed/quality tradeoff for workloads that mix `people_search` with `web_search` and `fetch_url`. Each tier defines a model, reasoning effort, tool selection, per-tool token budgets, and step limits. Use them as starting points and adjust per your latency, depth, and accuracy needs.

| Tier              | Model                           | Reasoning | Tools                                      | Max Steps | Use When                                                                    |
| ----------------- | ------------------------------- | --------- | ------------------------------------------ | --------- | --------------------------------------------------------------------------- |
| **pro**           | `openai/gpt-5-mini`             | medium    | `people_search`, `web_search`, `fetch_url` | 5         | Balanced people/web research with moderate depth                            |
| **deep**          | `google/gemini-3-flash-preview` | high      | `people_search`, `web_search`, `fetch_url` | 10        | Deeper analysis when latency budget is moderate but quality matters         |
| **advanced-deep** | `openai/gpt-5`                  | medium    | `people_search`, `web_search`, `fetch_url` | 10        | High-quality, multi-step research with long context                         |
| **ultra-deep**    | `openai/gpt-5.5`                | high      | `people_search`, `web_search`, `fetch_url` | 50        | Maximum-depth investigations with the largest token budgets and step counts |

<Info>
  The `bigtokens` settings used by pro, deep, and advanced-deep refer to `max_tokens=10000` and `max_tokens_per_page=1000` on the `people_search` and `web_search` tools. The `xltokens` settings used by ultra-deep refer to `max_tokens=20000` and `max_tokens_per_page=2000`.
</Info>

<Warning>
  **ultra-deep heads-up:** `openai/gpt-5.5` with high reasoning and streaming may be flaky upstream. If requests hang, fall back to `medium` reasoning effort or disable streaming.
</Warning>

### pro

Balanced configuration with all three tools enabled and moderate reasoning effort.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5-mini",
      reasoning={"effort": "medium"},
      tools=[
          {
              "type": "people_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
          },
          {
              "type": "web_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
          },
          {"type": "fetch_url"},
      ],
      max_steps=5,
      input="Find the head of platform engineering at Notion and summarize their background.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5-mini',
    reasoning: { effort: 'medium' },
    tools: [
      {
        type: 'people_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
      },
      {
        type: 'web_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
      },
      { type: 'fetch_url' },
    ],
    max_steps: 5,
    input: 'Find the head of platform engineering at Notion and summarize their background.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5-mini",
      "reasoning": {"effort": "medium"},
      "tools": [
        {
          "type": "people_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000
        },
        {
          "type": "web_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000
        },
        {"type": "fetch_url"}
      ],
      "max_steps": 5,
      "input": "Find the head of platform engineering at Notion and summarize their background."
    }'
  ```
</CodeGroup>

### deep

Higher reasoning effort and step count with a generous output budget for fuller multi-source answers.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="google/gemini-3-flash-preview",
      reasoning={"effort": "high"},
      tools=[
          {
              "type": "people_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
          },
          {
              "type": "web_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
          },
          {"type": "fetch_url"},
      ],
      max_steps=10,
      max_output_tokens=16000,
      input="Map the executive team at a mid-size SaaS company and explain each leader's prior roles.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'google/gemini-3-flash-preview',
    reasoning: { effort: 'high' },
    tools: [
      {
        type: 'people_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
      },
      {
        type: 'web_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
      },
      { type: 'fetch_url' },
    ],
    max_steps: 10,
    max_output_tokens: 16000,
    input: "Map the executive team at a mid-size SaaS company and explain each leader's prior roles.",
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google/gemini-3-flash-preview",
      "reasoning": {"effort": "high"},
      "tools": [
        {
          "type": "people_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000
        },
        {
          "type": "web_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000
        },
        {"type": "fetch_url"}
      ],
      "max_steps": 10,
      "max_output_tokens": 16000,
      "input": "Map the executive team at a mid-size SaaS company and explain each leader'\''s prior roles."
    }'
  ```
</CodeGroup>

### advanced-deep

A frontier-model configuration for high-quality, multi-step research when latency budget is generous.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5",
      reasoning={"effort": "medium"},
      tools=[
          {
              "type": "people_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
          },
          {
              "type": "web_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
          },
          {"type": "fetch_url"},
      ],
      max_steps=10,
      input="Identify the top product leaders across three competitors and compare their backgrounds.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5',
    reasoning: { effort: 'medium' },
    tools: [
      {
        type: 'people_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
      },
      {
        type: 'web_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
      },
      { type: 'fetch_url' },
    ],
    max_steps: 10,
    input: 'Identify the top product leaders across three competitors and compare their backgrounds.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5",
      "reasoning": {"effort": "medium"},
      "tools": [
        {
          "type": "people_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000
        },
        {
          "type": "web_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000
        },
        {"type": "fetch_url"}
      ],
      "max_steps": 10,
      "input": "Identify the top product leaders across three competitors and compare their backgrounds."
    }'
  ```
</CodeGroup>

### ultra-deep

Maximum-depth configuration with the largest token budgets, the highest step count, and `xltokens` per-tool settings. Best for exhaustive investigations.

<Warning>
  `openai/gpt-5.5` with high reasoning and streaming may be flaky upstream. If requests hang, switch to `medium` effort or use a non-streaming call.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      reasoning={"effort": "high"},
      tools=[
          {
              "type": "people_search",
              "max_tokens": 20000,
              "max_tokens_per_page": 2000,
          },
          {
              "type": "web_search",
              "max_tokens": 20000,
              "max_tokens_per_page": 2000,
          },
          {"type": "fetch_url"},
      ],
      max_steps=50,
      max_output_tokens=32000,
      input="Build a complete organizational map of a target company, including reporting lines and prior employment history for every named leader.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    reasoning: { effort: 'high' },
    tools: [
      {
        type: 'people_search',
        max_tokens: 20000,
        max_tokens_per_page: 2000,
      },
      {
        type: 'web_search',
        max_tokens: 20000,
        max_tokens_per_page: 2000,
      },
      { type: 'fetch_url' },
    ],
    max_steps: 50,
    max_output_tokens: 32000,
    input: 'Build a complete organizational map of a target company, including reporting lines and prior employment history for every named leader.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "reasoning": {"effort": "high"},
      "tools": [
        {
          "type": "people_search",
          "max_tokens": 20000,
          "max_tokens_per_page": 2000
        },
        {
          "type": "web_search",
          "max_tokens": 20000,
          "max_tokens_per_page": 2000
        },
        {"type": "fetch_url"}
      ],
      "max_steps": 50,
      "max_output_tokens": 32000,
      "input": "Build a complete organizational map of a target company, including reporting lines and prior employment history for every named leader."
    }'
  ```
</CodeGroup>

## Parameters

| Parameter             | Type    | Required | Description                                                                       |
| --------------------- | ------- | -------- | --------------------------------------------------------------------------------- |
| `type`                | string  | Yes      | Must be `"people_search"`.                                                        |
| `max_tokens`          | integer | No       | Maximum total tokens for people-search context when using explicit token budgets. |
| `max_tokens_per_page` | integer | No       | Maximum tokens extracted per result page when using explicit token budgets.       |

## Response Shape

When `people_search` runs, the response can include a `people_search_results` output item before the final assistant message. The envelope contains the agent's generated `queries` and a `results` array whose entries share the same shape as `search_results` (id, url, title, snippet, source, last\_updated). The final `usage` object includes token counts, cost details, and `tool_calls_details.people_search.invocation` when tool-call usage is reported.

```json theme={null}
{
  "output": [
    {
      "type": "people_search_results",
      "queries": ["head of platform engineering Notion"],
      "results": [
        {
          "id": 1,
          "url": "https://example.com/profile",
          "title": "Example professional profile",
          "snippet": "A short snippet describing the professional result.",
          "source": "web"
        }
      ]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The answer generated from people-search results."
        }
      ]
    }
  ],
  "usage": {
    "tool_calls_details": {
      "people_search": {
        "invocation": 1
      }
    }
  }
}
```

## Pricing

Each invocation of the `people_search` tool is billed at **\$5 per 1,000 tool invocations**. See the [Pricing](/docs/getting-started/pricing) page for full details.

## Limits / Quotas

People Search runs inside Agent API requests and is subject to your Agent API rate limits. See [Rate Limits & Usage Tiers](/docs/admin/rate-limits-usage-tiers#agent-api-rate-limits) for tier-based request limits.

| Limit           | How it applies                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| **Rate limits** | Counts against your Agent API request rate limits. No separate `people_search` tool-call quotas apply. |

## Next Steps

<CardGroup cols={2}>
  <Card title="Web Search" icon="world-search" href="/docs/agent-api/tools/web-search">
    Search the web for source-grounded context.
  </Card>

  <Card title="Fetch URL Content" icon="file-text" href="/docs/agent-api/tools/fetch-url-content">
    Fetch full content from known URLs.
  </Card>

  <Card title="Finance Search" icon="chart-line" href="/docs/agent-api/tools/finance-search">
    Retrieve structured financial and market data.
  </Card>

  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API.
  </Card>
</CardGroup>