---
title: "Search people"
method: POST
path: "/people/search"
tags: ["People"]
---

# Search people

`POST /people/search`

## Request

- Base URL: `https://api.context.dev/v1`
- URL: `https://api.context.dev/v1/people/search`
- Auth: HTTP bearer

Find people with a natural-language query.

## Request body

- object
  - `query` string, required: Describe the people to find.
  - `filters` PeopleSearchFilters: Additional constraints every result must match.
    - `countries` string[]: Countries people live in as two-letter codes, such as US or GB.
    - `years_of_experience_min` integer: Minimum years of professional experience.
    - `years_of_experience_max` integer: Maximum years of professional experience.
  - `cursor` string: Use next_cursor with the same query and filters to fetch the next page.
  - `tags` string[]: Labels for filtering usage in the dashboard.

## Response `200`

Successful response

- object
  - `results` object[], required: Up to 10 matching people, most relevant first.
    - `name` string, nullable, required: Full name.
    - `description` string, nullable, required: What the person does.
    - `profiles` string[], required: Public professional profile URLs.
    - `location` object, required: Where the person lives.
      - `country_code` string, nullable, required: Country as a two-letter code, such as US or GB.
      - `region` string, nullable, required: State or region.
      - `city` string, nullable, required: City.
    - `role` object, required: The person’s current role.
      - `title` string, nullable, required: Job title.
      - `seniority` string, nullable, required: Seniority level.
      - `functions` string[], required: Areas of responsibility.
      - `started_on` string, nullable, required: Role start date (YYYY-MM-DD).
      - `company` object, nullable, required: Current employer, when known.
        - `name` string, nullable, required: Company name.
        - `domain` string, nullable, required: The company’s website domain.
    - `years_of_experience` integer, nullable, required: Years of professional experience.
    - `is_founder` boolean, nullable, required: Whether the person is currently a founder or co-founder.
    - `skills` string[], required: Professional skills.
    - `schools` string[], required: Schools attended.
  - `next_cursor` string, nullable: Pass as cursor to fetch the next page; null when there are no more results.
  - `key_metadata` KeyMetadata: Credits this request used and your remaining balance.
    - `credits_consumed` integer, required: Credits charged for this request.
    - `credits_remaining` integer, required: Credits remaining for your organization.
  - `request_id` string, uuid, required: Unique ID of this request, also in `X-Request-Id`. Include it when contacting support.

## Other responses

- `400`: Bad Request
- `401`: Missing or invalid API key.
- `408`: Request Timeout
- `429`: Rate limit exceeded. Organization concurrency rejections include structured error_data and subscription settings; follow Retry-After before retrying.
- `500`: Internal server error

## Changes

- **2026-10-23** `9e2ab7841fb1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/context/apis/brand-api/changes/people/search/post.md)

---

[API](https://skmtc.dev/context/apis/brand-api.md) · [All operations](https://skmtc.dev/context/apis/brand-api/llms.txt) · [OpenAPI document](https://skmtc.dev/context/apis/brand-api/revisions/9e2ab7841fb1?raw)