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. Add metadata labels, such as a campaign or customer ID, to find a search again later with GET /desearch/people/tasks?metadata.<key>=<value>.

    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.1 profile
    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.1 creator
    LinkedIn Profile SearchPOST /desearch/people/search/linkedinLinkedIn members by what they post and by their role. Reads headline, company, location, followers, and about.1 profile
    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.1 creator

    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. Up to 1,000 handles.
    filtersPlatform filters, below.
    metadataYour own labels for the search, for example {"campaign": "q4-outbound"}. Returned on the task and usable as a filter on the task list. The search never uses them. See Label your searches with metadata 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.

    On YouTube, min_subscribers and max_subscribers are the minimum and maximum subscriber count. A creator whose count is unknown does not pass either filter.

    Request header, the same on all four create routes:

    HeaderMeaning
    Idempotency-KeyOptional. Any unique string, for example a UUID, at most 200 characters. Sending the same key again returns the first search (HTTP 200) instead of starting and charging a new one.

    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, paused, or cancelling, 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.
    metadataThe labels sent with the search, or {} when it had none.
    interpretedHow the search understood the request: criteria and the queries it ran.
    completion_reasonWhy the search ended, below. null while it is queued, running or paused.
    coverage_limitedtrue when the search stopped on a budget (completion_reason cost_limit, candidate_budget or time_limit) before reaching count: there may be more matching people than it returned. Default false. The task status is still completed.
    warningsWhat made part of the search less reliable without failing it, below. [] when nothing did.
    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.

    completion_reason is one of:

    ValueMeaning
    count_reachedIt found count profiles.
    rounds_exhaustedIt ran every search it planned and found fewer than count.
    no_candidatesIts searches found nobody to check.
    zero_qualifiedIt checked the people its searches found and none fit.
    candidate_budgetIt checked as many candidates as a search of this count may: min(1000, max(150, count x 8)).
    cost_limitWhat searching cost reached what its results would bill, so it stopped.
    time_limitIt ran for its maximum time.
    cancelledIt was cancelled.
    failedAn error ended it (every search failed, or an internal error).

    status keeps its values. A search that stopped on a budget with fewer than count profiles, or with none, is still completed. Check coverage_limited.

    Each item in warnings has:

    FieldMeaning
    codepartial_enrichment: some candidates' profiles could not be read after search, so they were scored on what the search returned. Results among them have attributes.enrichment set to failed.
    platformx, youtube, linkedin, or tiktok.
    attemptedProfile lookups tried (YouTube: channels).
    enrichedLookups that read the profile.
    failedLookups that could not read the profile.
    by_reasonLinkedIn and TikTok: failed lookups by reason: not_found (private, removed, or not shown to logged-out visitors), rate_limited, timeout, upstream_error, request_error. YouTube: failed lookups by source (about_page_failed, innertube_failed); a channel still counts as enriched when another source answered, but may miss its About description, links or emails.
    messageA sentence that describes the warning, or null.

    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, concerns, criteria_checks, and fully_verified, below.
    attributesPlatform fields: verified (X, TikTok), headline and company (LinkedIn), region (TikTok). LinkedIn, TikTok and YouTube results also have enrichment: ok when the profile was read after search, failed when it could not be. Then enrichment_error says why (not_found, rate_limited, timeout, upstream_error, request_error), and fields such as location, followers, experience or channel links come from the search hit only or are missing.

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

    score.criteria_checks has one check per criterion: what the person's own profile and posts confirm. It is information only: a qualified result can still have criteria that are unknown. It is empty on results scored before 2026-10-20. Each check has:

    FieldMeaning
    criterionOne of the search's criteria, word for word.
    verdictmet: a quote from the person's profile or source shows it (quotes are checked word for word; one that is not there becomes unknown). not_met: the evidence contradicts it. unknown: nothing found shows it either way. For a disqualifier (is_disqualifier), met means it applies. A location is met only by the current location, headline or current role, not by a school or a past job.
    quoteThe verbatim text behind a met verdict, or null.
    source_urlWhere the quote is: the post, video or profile URL, or null.
    reasonA short explanation of the verdict.
    is_disqualifiertrue when the criterion is a disqualifier, so met means it applies. Absent on checks scored before the field existed.

    score.fully_verified is true when every criterion is met and no disqualifier (is_disqualifier) is. It can be true, false or null, and is absent on results scored before 2026-10-20.

    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.

    Reading results

    A finished search says why it stopped and how complete it is, and each person says what their own profile and posts confirm. Check these before you use the list:

    FieldWhat it tells youWhat to do
    completion_reasoncount_reached: it found count people. rounds_exhausted: it ran every search it planned and found fewer. no_candidates or zero_qualified: it found nobody, or nobody who fit, and costs nothing.When it found fewer people than you asked for, describe them more broadly.
    coverage_limitedtrue when a budget (cost_limit, candidate_budget, or time_limit) stopped the search before count, so more people may match. status is still completed.To look further, start a new search and put the handles you already have in exclude.
    warningspartial_enrichment: failed of attempted profiles could not be read after search, with by_reason. Those people were scored on the search hit only.Review the people whose attributes.enrichment is failed.
    attributes.enrichmentok when the profile was read after search, failed when it could not be (LinkedIn, TikTok, YouTube). enrichment_error says why.When it is failed, location, followers, experience, or channel links can be missing.
    score.criteria_checksOne check per criterion: met with the quote and source_url that show it, not_met, or unknown. is_disqualifier marks a disqualifier, where met means it applies.Read the checks that are not met to see what is unconfirmed.
    score.fully_verifiedtrue when every criterion is met and no disqualifier is.Treat false as something to check before you reach out. The person still qualified.

    A result, shortened:

    json
    { "platform": "linkedin", "handle": "jane-doe", "attributes": {"headline": "Software Engineer at Acme", "enrichment": "ok"}, "score": { "value": 82, "fully_verified": false, "criteria_checks": [ { "criterion": "Profile fit: Software engineers based in Tbilisi", "verdict": "met", "quote": "Software Engineer at Acme", "source_url": "https://www.linkedin.com/in/jane-doe", "reason": "Current role in Tbilisi.", "is_disqualifier": false }, { "criterion": "Topic signal: posts about backend development", "verdict": "unknown", "quote": null, "source_url": null, "reason": "No post shows it.", "is_disqualifier": false } ] } }

    For the result above, fully_verified is false because the Topic signal: posts about backend development check is unknown. Read the reason on each check that is not met to see what the profile and posts did not confirm.

    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, status (comma-separated, for example running,paused), and metadata.<key>=<value> (below), and page with cursor.

    Label your searches with metadata

    Add metadata to a search to tag it with your own labels: the campaign it belongs to, the workspace or customer it runs for, or the ID of the record in your own system. You can then list only the searches that carry a label, instead of keeping your own map of task IDs. The search never reads metadata, so labels do not change who is found or what the search costs.

    Send the labels as a JSON object of strings when you start the 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, "metadata": {"campaign": "q4-outbound", "workspace_id": "ws_42"} }'

    Every task response returns the labels as metadata: this POST, the task, pause, resume, cancel, and the task list. A search without labels returns {}. The 202 response, shortened:

    json
    { "task_id": "24330484-ff4e-44eb-b399-a1f6a265335e", "search_type": "x_profile_search", "platform": "x", "status": "queued", "query": "Indie hackers building in public who share their MRR", "count": 10, "result_count": 0, "reserved_cost_usd": 0.4, "metadata": {"campaign": "q4-outbound", "workspace_id": "ws_42"} }

    To list the searches with a label, add one metadata.<key>=<value> query parameter per label. A task must match every filter exactly:

    bash
    curl --get 'https://api.desearch.ai/desearch/people/tasks' \ --header "Authorization: $DESEARCH_API_KEY" \ --data-urlencode 'metadata.campaign=q4-outbound' \ --data-urlencode 'metadata.workspace_id=ws_42'

    --data-urlencode encodes values that contain spaces or &. When you page with cursor, send the same filters on every page. You can combine them with platform and status.

    RuleLimit
    Labels per searchUp to 10 keys.
    Keys1 to 40 characters: lowercase a-z, 0-9, _, ., or -.
    ValuesStrings of up to 200 characters.
    Filters per task list callUp to 3 metadata.<key>=<value> parameters.

    A search whose metadata breaks these rules fails with 422. On the task list, an invalid metadata.<key> filter returns 400.

    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 a minimum of 1 per search that finds anyone, as shown in 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, verified on a platform without verified accounts, or an invalid metadata.<key> filter on the task list.
    401Missing API key, or a dt_ or dsr_ key that is not valid.
    403A malformed Authorization value, such as an unreplaced placeholder like YOUR_API_KEY. See Auth and API keys.
    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 or metadata that breaks the label rules.
    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.5.0 adds metadata to the four search methods and a metadata filter to list_people_tasks. 1.6.0 adds the result fields: completion_reason, coverage_limited, and warnings on PeopleTask, criteria_checks, fully_verified, and unverified_criteria on PeopleScore, and Person.enrichment. 1.6.1 adds is_disqualifier on each check. 1.6.1 is not on PyPI yet; install it from GitHub with pip install "desearch-py @ git+https://github.com/Desearch-ai/desearch.py@3488e8aec01b96cc423879e98bef183c845e3ccf". 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. 1.7.0 adds metadata to the four search methods and a metadata option to listPeopleTasks. 1.8.0 adds types for the result fields and unverifiedCriteria(score), which returns the checks that are not met, plus the disqualifiers that are met. A check without is_disqualifier, scored before the field existed, counts as a disqualifier when its criterion names one, such as disqualify or exclude. 1.8.1 adds is_disqualifier on each check. See the JavaScript SDK.
    • MCP: the hosted MCP server exposes the tools people-search, people-search-status, people-search-pause, people-search-resume, people-search-cancel, people-search-tasks, and people-profiles. From desearch-mcp-server 0.3.0, people-search takes an optional metadata argument and people-search-tasks can filter by it. From 0.3.2, task summaries show completion_reason, coverage_limited, and warnings, and each person shows fully_verified and unverified_criteria. See MCP.

    Related