> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryhuntr.com/llms.txt > Use this file to discover all available pages before exploring further. # Search 650M people with structured filters or natural language > **Requires `x-api-key` header.** Rate limit: 5 requests/second per API key. Search 650M+ people in one of two modes: send a structured `query`, or send a natural-language `semantic_query` with optional hard `filters`. Explicit `filters` override generated fields. **Semantic pagination:** The first semantic response includes `resolved_query`. For later pages, send that object as `query` with `pagination.token`. Semantic requests containing a token are rejected. **One page per request:** Each call returns at most `pagination.size` people (default 100, max 200). **Filter logic:** Job titles use contains matching and semantic mode expands common title variants. Prefer `currentCompanyWebsite` over `currentCompanyName` for employer filtering. Employer headcount, employer revenue, employer funding stage, and employer industry are not native people filters. Use **POST /person-search-count** with a structured query to preview `total` for free. **Price:** $0.0003 per person returned. Translation failures and empty results are free. ## OpenAPI ````yaml /openapi.json post /person-search openapi: 3.0.3 info: title: Huntr — The GTM Intelligence API description: >- Give AI agents company, people, contact, and web intelligence through one API. Search accounts, build targeted lists, enrich leads, find contacts, and uncover buying signals. **Authentication:** Authenticated endpoints require an `x-api-key` header with your Huntr API key. Get a key by signing up via `POST /keys/create`. Public endpoints (pricing, sign-up, health) work without a key. **Rate limit:** 5 requests/second per API key on authenticated endpoints. version: 2.0.0 servers: - url: https://api.tryhuntr.com security: [] tags: - name: Research description: >- Research one company, person, team, or focused business question and return a sales-ready answer. Lite, standard, and deep tiers. - name: Companies description: >- Search companies and enrich firmographics. Per-result pricing on search; count endpoints are free. - name: People description: >- Search people and enrich contacts — work email, phone, and related lookup endpoints. - name: LinkedIn description: >- LinkedIn URL discovery, company and profile pages, posts, reactions, and comments. - name: X description: X profiles, posts, search results, and thread context. - name: Web description: >- Find and analyze pages on a domain, plus tech stack, domain contacts, and job postings. - name: Account description: >- Sign up, verify email, recover keys, check balance, view usage, add credits, and read the public pricing matrix. - name: System description: Health check. paths: /person-search: post: tags: - People summary: Search 650M people with structured filters or natural language description: >- **Requires `x-api-key` header.** Rate limit: 5 requests/second per API key. Search 650M+ people in one of two modes: send a structured `query`, or send a natural-language `semantic_query` with optional hard `filters`. Explicit `filters` override generated fields. **Semantic pagination:** The first semantic response includes `resolved_query`. For later pages, send that object as `query` with `pagination.token`. Semantic requests containing a token are rejected. **One page per request:** Each call returns at most `pagination.size` people (default 100, max 200). **Filter logic:** Job titles use contains matching and semantic mode expands common title variants. Prefer `currentCompanyWebsite` over `currentCompanyName` for employer filtering. Employer headcount, employer revenue, employer funding stage, and employer industry are not native people filters. Use **POST /person-search-count** with a structured query to preview `total` for free. **Price:** $0.0003 per person returned. Translation failures and empty results are free. requestBody: required: true content: application/json: schema: type: object oneOf: - required: - query - required: - semantic_query properties: semantic_query: type: string maxLength: 8000 description: >- Natural-language description of the people to find. Mutually exclusive with `query`. The response includes `resolved_query` for deterministic pagination. filters: type: object description: >- Optional hard constraints used only with `semantic_query`. Uses the same people filter fields and shapes as `query`. Explicit fields override generated fields. additionalProperties: true query: type: object description: >- At least one filter required. Combine multiple filters — all must match (AND). See each field for match rules. Use POST /person-search-count to preview `total` for free. properties: firstname: type: object description: >- **Person's first name.** Open text. Substring match — any profile whose first name contains the string. Example: `{ "include": ["John"] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. lastname: type: object description: >- **Person's last name.** Open text, substring match. Example: `{ "include": ["Collison"] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. currentJobTitle: type: object description: >- **Current job title.** Open text — **contains** match: the keyword appears anywhere in the title (e.g. `"engineer"` matches "Software Engineer"). No synonym expansion: list variants explicitly (`CTO`, `Chief Technology Officer`). OR across values in `include`. Example: `{ "include": ["CTO", "Chief Technical Officer"] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. pastJobTitle: type: object description: >- **Past job title** (previous roles only). Same contains-match rules as `currentJobTitle`. Use when targeting alumni of a role, not current holders. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. currentCompanyName: type: object description: >- **Current employer name.** Open text, fuzzy/substring match — can return wrong companies with similar names. **Prefer `currentCompanyWebsite`** when you know the domain (`stripe.com`). Example: `{ "include": ["Stripe"] }`. Do not use to mean "works at a company with a LinkedIn page" — use website/domain filters instead. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. pastCompanyName: type: object description: >- **Past employer name** (previous companies only). Same fuzzy match as `currentCompanyName`. Use for alumni searches. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. currentCompanyUrn: type: object description: >- **Numeric URN of the person's current company.** Example: `{ "include": ["1234", "5678"] }`. Use when you have company URNs from a company export. Not the full LinkedIn URN string. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. pastCompanyUrn: type: object description: >- **Numeric URN of a past employer.** Same format as `currentCompanyUrn`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. currentCompanyWebsite: type: object description: >- **Current employer's website or domain (exact).** Example: `stripe.com` or `https://www.stripe.com`. **Best filter for "people at company X"** when you know the domain. Do **not** use `linkedin.com` — that matches anyone whose employer has a LinkedIn page, not a specific company. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. pastCompanyWebsite: type: object description: >- **Past employer's website or domain.** Same rules as `currentCompanyWebsite` for previous jobs. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. currentCompanyId: type: object description: >- **Current company identifier (flexible).** Accepts domain (`stripe.com`), numeric URN, LinkedIn company URL, or vanity name (`stripe`). Equivalent to company search `companyId` — use when you have mixed ID formats from exports. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. pastCompanyId: type: object description: >- **Past company identifier.** Same accepted formats as `currentCompanyId`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. school: type: object description: >- **School or university attended.** Open text, substring match. Example: `{ "include": ["Stanford", "Harvard"] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. languages: type: object description: >- **Languages spoken.** Language name or **alpha-2 code** (e.g. `EN`, `FR`). Example: `{ "include": ["EN"] }` with `{ "location": { "include": ["FR"] } }` for English speakers in France. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. skills: type: object description: >- **Skills listed on the profile.** Open text, substring match. Example: `{ "include": ["JavaScript", "Python"] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. location: type: object description: >- **Person's location** (where they are based). City, state, or country; **alpha-2 country codes** (`US`, `GB`) work best. Example: `{ "include": ["US"] }`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. keyword: type: object description: >- **Full-profile keyword search** — scans current and past titles, descriptions, headline, skills, education, etc. Open text. Use for broad concepts (e.g. `CEO`, `Co-Founder`) when no dedicated filter fits. Not a replacement for listing job-title variants in `currentJobTitle`. properties: include: type: array items: type: string description: >- Match companies where this field matches any listed value. exclude: type: array items: type: string description: Exclude companies matching any listed value. pagination: type: object description: >- One page per request (no auto-fetch). `size`: companies/people returned this call (default 100, max 200). `token`: copy from the previous response `pagination.token` to get the next page — keep the same `query`. Tokens expire; do not change the query between pages. properties: size: type: integer minimum: 1 maximum: 200 default: 100 description: >- Page size for this request (1–200). You are charged per row returned, up to this size. token: type: string description: >- Opaque cursor from the prior response. Omit on the first page. examples: semantic: summary: Natural-language people discovery with a hard location filter value: semantic_query: VPs of Sales at cybersecurity companies filters: location: include: - US pagination: size: 10 by_title: summary: CTOs in the US value: query: currentJobTitle: include: - CTO - Chief Technical Officer location: include: - US pagination: size: 10 by_company: summary: Engineers at a company value: query: currentJobTitle: include: - engineer currentCompanyWebsite: include: - stripe.com pagination: size: 5 by_keyword: summary: By keyword value: query: keyword: include: - CEO - Co-Founder pagination: size: 5 responses: '200': description: Person search results. content: application/json: schema: type: object properties: success: type: boolean request_id: type: string people: type: array description: Matching people. items: type: object properties: name: type: string description: Full name. linkedin_url: type: string description: LinkedIn profile URL. headline: type: string bio: type: string location: type: string title: type: string description: Current or most recent job title. job_description: type: string job_start_date: type: string company: type: string description: Current or most recent employer. website: type: string description: Employer website or domain. company_linkedin_url: type: string company_linkedin_urn: type: string description: Numeric LinkedIn company URN for the employer. company_industry: type: string company_employee_count: type: integer company_headquarters: type: string company_description: type: string total: type: integer description: >- Total people matching the query in the database (not the length of people). resolved_query: type: object description: >- Final structured query generated for a semantic request, including explicit filters. Send this as `query` with the pagination token for later pages. additionalProperties: true pagination: type: object description: >- Upstream pagination cursor when more pages exist. Pass pagination.token back on the next request with the same query. properties: token: type: string description: Opaque cursor for the next page. size: type: integer description: Upstream page size metadata. price: type: number description: Cost in USD. $0.0003 × number of people returned. credits_remaining: type: number example: success: true request_id: req_1746123456_ps1x2y people: - name: Patrick Collison linkedin_url: https://www.linkedin.com/in/patrickcollison headline: CEO at Stripe title: CEO company: Stripe website: https://stripe.com location: San Francisco, California, United States total: 4 resolved_query: currentJobTitle: include: - VP Sales - Vice President Sales keyword: include: - cybersecurity location: include: - US pagination: token: eyJ... size: 1 price: 0.0003 credits_remaining: 4.9997 '400': description: Missing or invalid query. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Insufficient credits. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Search failed. Credits are refunded automatically. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: >- The natural-language query could not be translated safely. No credits are charged. content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] components: schemas: Error: type: object properties: error: type: string description: Human-readable error message. required: - error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your Huntr API key. Get one at tryhuntr.com. Pass as x-api-key header on all authenticated requests. ````