DocumentationAPI Reference
    People Search API

    People Search API

    People Search finds people, not posts. Describe who you want in plain language, for example "Indie hackers building in public who share their MRR". Desearch searches public posts, videos, and profiles on one platform, reads each matching profile, and scores how well each person fits. Every result has a fit score, the reasons it matched, and the posts or videos behind the match. Public data only.

    Who this page is for

    Humans

    Start a search with one POST, then poll the task, read the people it found, and download them as CSV. The search runs in the background and usually takes 1 to 5 minutes. Full schemas are in the API Reference.

    Agents / tool authors

    A search is a background task. The POST returns a task_id at once, with no people in it. Poll GET /desearch/people/tasks/{task_id} and read GET /desearch/people/tasks/{task_id}/results with the cursor it returns. The POST is the only billed call. Send an Idempotency-Key header so a retried call does not start, or pay for, a second search.

    For posts that match a keyword, use the X API or the Social APIs. People Search returns a list of people.

    Which surface should I use?

    GoalUseNot this
    A list of people or creators who match a descriptionPeople Search (this page)X or TikTok post search
    Posts on X by keyword, user, or threadX APIPeople Search
    One known TikTok, Instagram, or Facebook profile, its posts, or commentsSocial APIsPeople Search
    People your earlier searches already foundGET /desearch/people/profilesA new search

    Services

    ServiceRouteWhat it findsMinimum billed per search that finds anyone
    X Profile SearchPOST /desearch/people/search/xX accounts by what they post and how they describe themselves. Reads bio, followers, website, and location.5 profiles
    YouTube Creator SearchPOST /desearch/people/search/youtubeYouTube creators by what their videos are about. Reads the About section, subscribers, country, links, and a public email when the creator lists one.3 creators
    LinkedIn Profile SearchPOST /desearch/people/search/linkedinLinkedIn members by what they post and by their role. Reads headline, company, location, followers, and about.2 profiles
    TikTok Creator SearchPOST /desearch/people/search/tiktokTikTok creators by what their videos are about. Reads bio, followers, likes, latest videos, and a public email when the bio lists one.2 creators

    Base URL: https://api.desearch.ai
    Auth: Authorization: $DESEARCH_API_KEY (raw key in examples).

    First call: X Profile Search

    bash
    curl --request POST 'https://api.desearch.ai/desearch/people/search/x' \ --header "Authorization: $DESEARCH_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: $(uuidgen)" \ --data '{"query": "Indie hackers building in public who share their MRR", "count": 10}'

    The response is 202 Accepted with the new task. Its status is queued, and reserved_cost_usd is the amount reserved for count people. Keep task_id for every call below. Repeating the call with the same Idempotency-Key returns 200 with the same task and is not charged again.

    Request body fields, the same on all four routes:

    FieldMeaning
    queryRequired. Who you are looking for, in plain language. 3 to 1000 characters.
    countHow many qualified people to find. 5 to 200, default 25. The search reserves this many and bills only the people it delivers.
    min_scoreOnly return people with at least this fit score, 0 to 100.
    excludeHandles to leave out, for example people you already contacted.
    filtersPlatform filters, below.
    Platformfilters fields
    Xmin_followers, max_followers, verified_only, countries, keywords, exclude_keywords
    YouTubemin_subscribers, max_subscribers, countries, require_contact, keywords, exclude_keywords
    LinkedInmin_followers, max_followers, countries, keywords, exclude_keywords
    TikTokmin_followers, max_followers, require_contact, keywords, exclude_keywords

    On YouTube, require_contact keeps only creators with a public email or contact link. On TikTok, it keeps only creators with a public email in their bio. The body accepts only the fields above, so a filter from another platform fails validation with 422.

    Poll the task

    bash
    curl --request GET "https://api.desearch.ai/desearch/people/tasks/$TASK_ID" \ --header "Authorization: $DESEARCH_API_KEY"

    Poll every few seconds. The task moves through queued, running, and sometimes pausing or paused, then ends as completed, partial, failed, cancelled, or expired. While it runs, stage is planning, searching, processing, or finalizing, and result_count counts the people found so far.

    Task fieldMeaning
    task_id, platform, search_typeThe task and the service it runs.
    status, stage, progressWhere the search is.
    count, result_countPeople requested and people found so far.
    interpretedHow the search understood the request: criteria and the queries it ran.
    reserved_cost_usdAmount reserved when the task was created.
    final_cost_usd, refunded_usdFinal cost and the returned part of the reservation, once the task has ended.
    results_expire_atWhen the results stop being available, 30 days after the search ends.
    linksPaths for this task, its results, and its export.

    Read the results

    People arrive while the search is still running. Start with cursor=0, then pass each response's next_cursor back as cursor:

    bash
    curl --request GET "https://api.desearch.ai/desearch/people/tasks/$TASK_ID/results?cursor=0&limit=100" \ --header "Authorization: $DESEARCH_API_KEY"

    When has_more is false, you have every person found so far. Keep the last next_cursor and call again later to get only the people found since. Results are in the order they were found.

    Each item in results is one person:

    FieldMeaning
    id, platform, handle, url, name, avatar_urlWho the person is.
    bio, locationProfile text.
    metricsAudience and activity counts, such as followers (subscribers on YouTube).
    links, contactsPublic links and contact details the search found, such as an email listed in a bio.
    evidenceThe posts or videos behind the match.
    scorevalue (0 to 100), a one-line summary of why the person matched, reasons, and concerns.
    attributesPlatform fields: verified (X, TikTok), headline and company (LinkedIn), region (TikTok).

    Fields that a platform does not report can be missing or null. Treat a missing value as unknown, not zero.

    Download a CSV

    bash
    curl --request GET "https://api.desearch.ai/desearch/people/tasks/$TASK_ID/export?format=csv" \ --header "Authorization: $DESEARCH_API_KEY" \ --output people.csv

    format=jsonl returns JSON Lines. The export accepts the same filters as the profiles library below, for example has=email to keep only people with a public email. Results stay available for 30 days after the search ends. After that, results and export return 410.

    Pause, resume, or cancel

    CallWhat happens
    POST /desearch/people/tasks/{task_id}/pauseA queued search pauses at once. A running search finishes its current batch first (pausing, then paused). People found so far stay available. A search paused for more than 7 days is cancelled.
    POST /desearch/people/tasks/{task_id}/resumeContinues a paused search from where it stopped. It is not charged again.
    POST /desearch/people/tasks/{task_id}/cancelStops the search. You pay only for the people it delivered, and a search cancelled before it starts costs nothing.

    When the task's status does not allow the action, the call returns 409 with detail and the current task.

    GET /desearch/people/tasks lists your company's tasks, newest first. Filter with platform and status (comma-separated, for example running,paused) and page with cursor.

    Profiles library

    GET /desearch/people/profiles lists everyone your searches found on one platform, one entry per person. Each entry is the person's best-scoring result plus found_by: the search that found them and how many of your searches did. Searches whose results expired are left out.

    bash
    curl --request GET 'https://api.desearch.ai/desearch/people/profiles?platform=x&has=email&min_audience=1000&sort=score' \ --header "Authorization: $DESEARCH_API_KEY"
    ParameterMeaning
    platformRequired. x, youtube, linkedin, or tiktok.
    qText in the name, handle, bio, or location.
    sortscore (default), recent, or audience.
    limit, cursorPage size (1 to 200, default 50) and the next_cursor from the previous page. next_cursor is null on the last page.
    hasComma-separated channels every person must have: email, website, x, linkedin, instagram, youtube, tiktok.
    min_audience, max_audienceFollowers (subscribers on YouTube).
    min_scoreMinimum fit score.
    locationText in the location, for example united states.
    verifiedOnly verified accounts. X and TikTok only: on YouTube or LinkedIn it returns 400.

    GET /desearch/people/profiles/export?platform=x&format=csv downloads the same list as CSV or JSON Lines, up to 10,000 people.

    Billing

    • Starting a search is the only billed call. It reserves count people at the service's rate. The response carries the usual X-Desearch-Cost-Usd, X-Desearch-Usage-Count, X-Desearch-Service, and X-Desearch-Currency headers, and the task shows reserved_cost_usd.
    • When the search ends, you pay only for the qualified people it delivered, with the per-search minimum from the Services table above. The rest of the reservation is returned automatically.
    • A search that finds nobody is free.
    • Polling, results, exports, pause, resume, cancel, the task list, and the profiles library are free.
    • 402 means the balance cannot cover the reservation. 429 means too many of your searches are already queued, running, or paused.

    Rates per 1,000 people are on the pricing page. Console shows the rates for your account.

    Errors

    StatusMeaning
    400Unknown platform, sort, status, cursor, or has channel, or verified on a platform without verified accounts.
    401Missing or invalid API key.
    402Not enough credits for the reservation.
    404Task not found.
    409Pause, resume, or cancel does not apply to the task's current status.
    410Results expired, 30 days after the search ended.
    422Invalid request body or parameters, including a search filter the platform does not have.
    429Too many searches already queued, running, or paused.

    SDKs and MCP

    • Python: desearch-py 1.4.0 adds x_profile_search, youtube_creator_search, linkedin_profile_search, tiktok_creator_search, the task and profile methods, and the helpers wait_for_people_task and iter_people_results. 1.4.0 is not on PyPI yet; install it from GitHub with pip install "desearch-py @ git+https://github.com/Desearch-ai/desearch.py@d441533ca3ede221114e413077c2f5b0d5062d5d". See the Python SDK.
    • JavaScript: desearch-js 1.6.0 adds xProfileSearch, youtubeCreatorSearch, linkedinProfileSearch, tiktokCreatorSearch, the task and profile methods, and the helpers waitForPeopleTask and iterPeopleResultPages. See the JavaScript SDK.
    • MCP: the tools people-search, people-search-status, people-search-control, people-search-tasks, and people-profiles. See MCP.

    Related