Skip to main content

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

deep

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

advanced-deep

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

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.

Parameters

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.

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

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.