People Search

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

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.

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”

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

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.6-luna`	medium	`people_search`, `web_search`, `fetch_url`	5	Balanced people/web research with moderate depth
deep	`google/gemini-3.8-flash`	high	`people_search`, `web_search`, `fetch_url`	10	Deeper analysis when latency budget is moderate but quality matters
advanced-deep	`openai/gpt-5.6-sol`	medium	`people_search`, `web_search`, `fetch_url`	10	High-quality, multi-step research with long context
ultra-deep	`openai/gpt-5.6-sol`	high	`people_search`, `web_search`, `fetch_url`	50	Maximum-depth investigations with the largest token budgets and step counts

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.

ultra-deep heads-up: openai/gpt-5.6-sol with high reasoning and streaming may be flaky upstream. If requests hang, fall back to medium reasoning effort or disable streaming.

pro

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

from perplexity import Perplexity

client = Perplexity()


def get_output_text(response) -> str:
    return "".join(
        content.text
        for item in response.output or []
        if getattr(item, "type", None) == "message"
        for content in getattr(item, "content", None) or []
        if getattr(content, "type", None) == "output_text"
    )


response = client.responses.create(
    model="openai/gpt-5.6-luna",
    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="Who is the current CEO of Notion, and what was their background before joining the company?",
)

print(get_output_text(response))

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-5.6-luna',
  reasoning: { effort: 'medium' },
  tools: [
    {
      type: 'people_search',
      // @ts-expect-error -- the API accepts people_search token limits, but the SDK types don't list them yet
      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: 'Who is the current CEO of Notion, and what was their background before joining the company?',
});

console.log(response.output_text);

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.6-luna",
    "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": "Who is the current CEO of Notion, and what was their background before joining the company?"
  }'

Response

{
  "id": "3f87daf1-90d8-421a-9459-45f4ca027591",
  "results": [
    {
      "snippet": "In today’s article, we will meet Ivan Zhao, a visionary entrepreneur, coding genius, and co-founder of Notion, a groundbreaking company now valued at $10 billion.\n...\nIn the early 2010s, Ivan Zhao...",
      "title": "The Phenomenal Journey of Ivan Zhao, Notion's Founder - KITRUM",
      "url": "https://kitrum.com/blog/the-phenomenal-journey-of-ivan-zhao-notions-founder/",
      "date": "2025-01-14",
      "last_updated": "2025-07-09"
    },
    {
      "snippet": "Notion Labs, Inc. was created as a startup in San Francisco, California, founded in 2013 by Ivan Zhao, Akshay Kothari, Chris Prucha, Jessica Lam, Simon Last, and Toby Schachman.",
      "title": "Notion (productivity software) - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Notion_(productivity_software)",
      "date": "2018-10-10",
      "last_updated": "2026-05-18"
    },
    {
      "snippet": "",
      "title": "Notion's Founder Deleted 3 Years of Work. Here's Why. - YouTube",
      "url": "https://www.youtube.com/watch?v=hYWMyXMkZmE",
      "date": "2026-03-04",
      "last_updated": "2026-05-26"
    }
  ],
  "server_time": null
}

deep

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

from perplexity import Perplexity

client = Perplexity()


def get_output_text(response) -> str:
    return "".join(
        content.text
        for item in response.output or []
        if getattr(item, "type", None) == "message"
        for content in getattr(item, "content", None) or []
        if getattr(content, "type", None) == "output_text"
    )


response = client.responses.create(
    model="google/gemini-3.8-flash",
    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 leadership team at Linear (linear.app) and summarize each leader's prior roles using publicly available sources.",
)

print(get_output_text(response))

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'google/gemini-3.8-flash',
  reasoning: { effort: 'high' },
  tools: [
    {
      type: 'people_search',
      // @ts-expect-error -- the API accepts people_search token limits, but the SDK types don't list them yet
      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 leadership team at Linear (linear.app) and summarize each leader's prior roles using publicly available sources.",
});

console.log(response.output_text);

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.8-flash",
    "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."
  }'

Response

{
  "id": "8d6f6fd4-1bd0-4646-b6c5-a0ac42d8cfc1",
  "results": [
    {
      "snippet": "## Meet the team behind Linear\nWe are designers and engineers.\n...\nWe are a diverse team of individuals, all makers at heart.\nWe’re hiring →\nKarri SaarinenCo-founder, CEO\nJori LalloCo-founder, CPO...",
      "title": "About",
      "url": "https://linear.app/about",
      "date": "2020-12-03",
      "last_updated": "2026-05-19"
    },
    {
      "snippet": "Linear is a software development company founded in 2019 by Karri Saarinen and Tuomas Artman.\n...\nThe Linear leadership team combines deep expertise in software engineering, product management, and...",
      "title": "Linear's Executive Team & Leadership | Meet Our Leaders - Exa",
      "url": "https://websets.exa.ai/websets/directory/linear-executives",
      "date": "2026-05-21",
      "last_updated": "2026-05-21"
    },
    {
      "snippet": "Linear has always been a fully remote company.\nToday, our small but mighty team is distributed across North America and Europe.\n...\nWe are all makers at heart and care deeply about the quality of our...",
      "title": "About - Linear",
      "url": "https://linear.app/about?_rsc=15b46",
      "date": "2025-12-19",
      "last_updated": "2026-01-18"
    }
  ],
  "server_time": null
}

advanced-deep

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

from perplexity import Perplexity

client = Perplexity()


def get_output_text(response) -> str:
    return "".join(
        content.text
        for item in response.output or []
        if getattr(item, "type", None) == "message"
        for content in getattr(item, "content", None) or []
        if getattr(content, "type", None) == "output_text"
    )


response = client.responses.create(
    model="openai/gpt-5.6-sol",
    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 current CEO of Notion, Linear, and Figma, and summarize each one's professional background.",
)

print(get_output_text(response))

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-5.6-sol',
  reasoning: { effort: 'medium' },
  tools: [
    {
      type: 'people_search',
      // @ts-expect-error -- the API accepts people_search token limits, but the SDK types don't list them yet
      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 current CEO of Notion, Linear, and Figma, and summarize each one\'s professional background.',
});

console.log(response.output_text);

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.6-sol",
    "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 current CEO of Notion, Linear, and Figma, and summarize each one\u0027s professional background."
  }'

Response

{
  "id": "5b5af173-6ae5-4cad-bddd-b1f64c4f71aa",
  "results": [
    {
      "snippet": "",
      "title": "Tools for the Future: Your best semester with Notion, Arc and Figma",
      "url": "https://www.youtube.com/watch?v=UuOI99qN9PU",
      "date": "2024-09-28",
      "last_updated": "2026-05-16"
    },
    {
      "snippet": "",
      "title": "The Figma vs. Notion Playbook: Interview Secrets, & Comp Data ...",
      "url": "https://superinterviews.substack.com/p/the-figma-vs-notion-playbook-interview",
      "date": "2025-10-30",
      "last_updated": "2026-05-03"
    },
    {
      "snippet": "And they are doing so in incredibly unique ways:\n1. **No product managers, just a head of product.** PM duties are distributed across engineering and design.\n...\nOne.\nWe hired Nan Yu a little over a...",
      "title": "How Linear builds product - Lenny's Newsletter",
      "url": "https://www.lennysnewsletter.com/p/how-linear-builds-product",
      "date": "2023-09-26",
      "last_updated": "2026-05-11"
    }
  ],
  "server_time": null
}

ultra-deep

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

openai/gpt-5.6-sol with high reasoning and streaming may be flaky upstream. If requests hang, switch to medium effort or use a non-streaming call.

from perplexity import Perplexity

client = Perplexity()


def get_output_text(response) -> str:
    return "".join(
        content.text
        for item in response.output or []
        if getattr(item, "type", None) == "message"
        for content in getattr(item, "content", None) or []
        if getattr(content, "type", None) == "output_text"
    )


response = client.responses.create(
    model="openai/gpt-5.6-sol",
    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 leadership map of Anthropic, including the executive team and direct reports to each VP, with prior employment history.",
)

print(get_output_text(response))

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-5.6-sol',
  reasoning: { effort: 'high' },
  tools: [
    {
      type: 'people_search',
      // @ts-expect-error -- the API accepts people_search token limits, but the SDK types don't list them yet
      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 leadership map of Anthropic, including the executive team and direct reports to each VP, with prior employment history.',
});

console.log(response.output_text);

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.6-sol",
    "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 leadership map of Anthropic, including the executive team and direct reports to each VP, with prior employment history."
  }'

Response

{
  "id": "276b823b-9651-4c63-87c3-6be6f3b51a99",
  "results": [
    {
      "snippet": "",
      "title": "List of Anthropic Executives & Org Chart - Clay",
      "url": "https://www.clay.com/dossier/anthropic-executives",
      "date": null,
      "last_updated": "2026-05-20"
    },
    {
      "snippet": "This Org Chart shows 64 people with power at Anthropic, including management, board directors and members of an independent oversight body.\nThe AI company has several OpenAI alumni across various...",
      "title": "Anthropic Org Chart & Company Structure Hierarchy - The Information",
      "url": "https://www.theinformation.com/org-charts/anthropic",
      "date": null,
      "last_updated": "2026-05-16"
    },
    {
      "snippet": "Anthropic is an AI safety and research company that’s working to build reliable, interpretable, and steerable AI systems.\n...\nHeadquarters\nSan Francisco, United States\n...\n## Org chart\nDario Amodei...",
      "title": "Anthropic | The Org",
      "url": "https://theorg.com/org/anthropic",
      "date": "2025-12-06",
      "last_updated": "2026-05-21"
    }
  ],
  "server_time": null
}

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.search_people.invocation when tool-call usage is reported.

{
  "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": {
      "search_people": {
        "invocation": 1
      }
    }
  }
}

Pricing

Each invocation of the people_search tool is billed at $5 per 1,000 tool invocations. See the 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 for tier-based request and token limits.

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

Next Steps

Web Search

Search the web for source-grounded context.

Fetch URL Content

Fetch full content from known URLs.

Finance Search

Retrieve structured financial and market data.

Agent API Quickstart

Get started with the Agent API.

Getting Started

Orchestrator API

Agent API

Search API

Embeddings API

Decisions API

Perplexity SDK

Admin & Management

Resources

Overview

Coverage

Query Tips

Tiered Configurations

pro

deep

advanced-deep

ultra-deep

Parameters

Response Shape

Pricing

Limits / Quotas

Next Steps

Web Search

Fetch URL Content

Finance Search

Agent API Quickstart

​Overview

​Coverage

​Query Tips

​Tiered Configurations

​pro

​deep

​advanced-deep

​ultra-deep

​Parameters

​Response Shape

​Pricing

​Limits / Quotas

​Next Steps

Web Search

Fetch URL Content

Finance Search

Agent API Quickstart

Overview

Coverage

Query Tips

Tiered Configurations

pro

deep

advanced-deep

ultra-deep

Parameters

Response Shape

Pricing

Limits / Quotas

Next Steps