To find people by description, send a plain-language query to one of the four Desearch People Search routes: POST /desearch/people/search/x, /youtube, /linkedin or /tiktok. The search runs in the background and returns a task_id at once. Poll the task, read profiles as they arrive, and export the shortlist as a CSV. Each profile comes with a fit score, the reasons it matched and the posts that prove it. The full reference is in the People Search guide.
This guide covers what the People Search API returns, where it fits (sales, recruiting, creator partnerships and more), how the task flow works, and how to keep a clean list across many searches.
What People Search does
You describe the people you want, in your own words. "Indie hackers building in public who share their MRR" is a valid query. People Search reads public data on the network you pick and returns profiles, not posts on X and LinkedIn, and creators, not videos on YouTube and TikTok.
Every result carries three things:
| What you get | Why it matters |
|---|---|
| Fit score (0 to 100) | Rank the shortlist and cut weak matches with min_score |
| Reasons it matched | See which parts of your description each person matches, and which ones a result does not confirm |
| Proof posts | The posts or videos behind the match, so you can check it yourself |
This is different from looking up a known account. If you already have a handle and want its details, the X user lookup app is the right pattern. People Search is for the people you don't know yet.
Where to use it: the use-case map
One description, four networks. Pick the network where the people you want actually show up.
| Use case | Networks | What to describe |
|---|---|---|
| Sales prospecting and account research | LinkedIn (by role), X (by what they post) | The role, the company type, the problem they talk about |
| Recruiting | LinkedIn, X | The skills and the work they share in public |
| Creator partnerships (sponsorships, affiliates, product seeding) | YouTube, TikTok | The niche, the format, the audience |
| Expert and source finding | X, LinkedIn | The topic they speak on with authority |
| Beta tester and community recruiting | X | The tools they use and the pain they post about |
| Feeding an agent a scored shortlist | All four | Any of the above, read through results and export |
For a lead list built from company signals rather than people, see the Hiring Signals Lead List in Python. If you want to find influencers on X without writing code, see Find Influencers on X with No Code.
How the task flow works
A people search takes longer than a single request, so it runs as a background task.
- Start the search.
POST /desearch/people/search/{network}returns atask_idright away. - Poll the task.
GET /desearch/people/tasks/{task_id}shows where the search is. - Read results while it runs.
GET /desearch/people/tasks/{task_id}/resultsreturns profiles as they arrive. You don't have to wait for the end. - Pause, resume or cancel.
POST /desearch/people/tasks/{task_id}/pause,/resumeand/cancelwork at any time. - Export.
GET /desearch/people/tasks/{task_id}/export?format=csvdownloads the shortlist.
Results stay available for 30 days.
Get an API key in Console
Create a key in Desearch Console. New accounts get $5 in API credits after attaching a card in Console, then pay as they go.
Start a search with cURL
curl --request POST 'https://api.desearch.ai/desearch/people/search/x' \
--header "Authorization: $DESEARCH_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"query": "Indie hackers building in public who share their MRR", "count": 10}'The response includes the task_id. Use it for every call that follows:
# Check the task
curl 'https://api.desearch.ai/desearch/people/tasks/TASK_ID' \
--header "Authorization: $DESEARCH_API_KEY"
# Read the profiles found so far
curl 'https://api.desearch.ai/desearch/people/tasks/TASK_ID/results' \
--header "Authorization: $DESEARCH_API_KEY"The task and result fields are listed in the POST /desearch/people/search/x reference and the results reference.
The same flow in Python
This version uses plain requests and is written from the routes above. It is not a captured run:
import os
import requests
BASE = "https://api.desearch.ai/desearch/people"
HEADERS = {"Authorization": os.environ["DESEARCH_API_KEY"]}
resp = requests.post(
f"{BASE}/search/x",
headers=HEADERS,
json={"query": "Indie hackers building in public who share their MRR", "count": 10},
timeout=60,
)
resp.raise_for_status()
task_id = resp.json()["task_id"]
print("task:", task_id)
# Check the task, then read whatever has arrived so far
task = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=60)
task.raise_for_status()
print(task.json())
results = requests.get(f"{BASE}/tasks/{task_id}/results", headers=HEADERS, timeout=60)
results.raise_for_status()
print(results.json())Call the task route again on an interval until the search ends. The status values are listed in the task reference.
Pick a network: X, YouTube, LinkedIn or TikTok
All four routes take the same core fields. What changes is where the search looks and what it reads.
X Profile Search
POST /desearch/people/search/x scans recent X posts on your topic, groups them by author, and reads each author's bio, followers, website and location. Use it when people are best described by what they post about. For X data beyond people, see the Twitter API page.
YouTube Creator Search
POST /desearch/people/search/youtube finds videos and channels on your topic, then reads the channel About section, subscribers, country and links. It also reads the creator's own website for publicly listed contact details, and returns a public email when the creator lists one.
LinkedIn Profile Search
POST /desearch/people/search/linkedin looks at public posts on your topic plus public profiles whose headline matches the role you describe. It reads headline, company, location, followers and about. Public data only.
TikTok Creator Search
POST /desearch/people/search/tiktok finds videos on your topic and accounts whose name or bio matches, then reads bio, followers, likes, latest videos and a public email in the bio when there is one. Public data only.
Reference pages: X, YouTube, LinkedIn, TikTok.
Narrow the shortlist
The request body has a few fields that keep the list tight:
| Field | What it does |
|---|---|
query | Required. Who you are looking for, in plain language |
count | How many profiles to find. Default 25, min 5, max 200 |
min_score | Keep only profiles at or above this fit score (0 to 100) |
exclude | Handles to leave out, up to 1,000. Use it for people you already contacted |
metadata | Your own labels for the search, at most 10 keys |
filters | Network-specific filters (below) |
Filters differ by network:
| Network | Filters |
|---|---|
| X | min_followers, max_followers, verified_only, countries, keywords, exclude_keywords |
| YouTube | min_subscribers, max_subscribers, countries, require_contact, keywords, exclude_keywords |
min_followers, max_followers, countries, keywords, exclude_keywords | |
| TikTok | min_followers, max_followers, require_contact, keywords, exclude_keywords |
TikTok has no countries filter, so you can't filter TikTok creators by location. The body accepts only the fields for that network, so a filter from another network fails validation with 422.
Here is a request that combines them. Swap in your own handles and thresholds:
curl --request POST 'https://api.desearch.ai/desearch/people/search/x' \
--header "Authorization: $DESEARCH_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"query": "Developers who post about building AI agents with search APIs",
"count": 50,
"min_score": 60,
"exclude": ["example_handle"],
"metadata": {"campaign": "beta-testers"},
"filters": {"min_followers": 500}
}'Read the results and export a CSV
Results are ranked people with a fit score, the reasons each one matched and the proof posts or videos. Read them while the search runs, or wait for the end.
To move the list into a sheet or CRM, download it as a CSV:
curl 'https://api.desearch.ai/desearch/people/tasks/TASK_ID/export?format=csv' \
--header "Authorization: $DESEARCH_API_KEY" \
--output shortlist.csvResults stay available for 30 days. See the export reference for the full options.
Keep one list across searches
If you run many searches on the same network, the same person can turn up more than once. GET /desearch/people/profiles lists everyone your searches found on one platform, with one entry per person. Each entry has found_by, so you can see which searches found that person.
You can search and filter the list, for example with has=email,instagram to keep people who have a public email and an Instagram link, and sort it by score, recency or audience.
GET /desearch/people/profiles/export downloads the whole list as CSV or JSON Lines, up to 10,000 people. The profiles list and its export are not billed.
Limits to know
People Search reads public data only. It doesn't reach private profiles or private contact details, and it doesn't promise every matching person on a network.
When a task ends, check three fields:
| Field | What it tells you |
|---|---|
completion_reason | Why the search stopped |
coverage_limited | Whether a budget stopped the search before it reached count |
warnings | Anything else worth knowing about the run |
If a search stops before count, try a broader description, loosen min_score, or relax the filters, then run it again with the people you already have in exclude.
Pricing
- X Profile Search: $40.00 / 1000 profiles (minimum 5 per search)
- YouTube Creator Search: $50.00 / 1000 creators (minimum 3)
- LinkedIn Profile Search: $50.00 / 1000 profiles (minimum 2)
- TikTok Creator Search: $50.00 / 1000 creators (minimum 2)
Confirm current rates in Console.
When a task starts, count profiles are reserved at the route price. At the end you pay only for the qualified profiles delivered, and the rest is returned automatically. A search that delivers no profiles costs nothing. See the pricing page for details.
FAQ
What is the Desearch People Search API?
A set of four routes that find people by description on X, YouTube, LinkedIn and TikTok. You send a plain-language query and get back scored profiles with the reasons they matched and the posts that prove it.
How is this different from a person search API that looks up a known user?
Lookup starts from a handle you already have. People Search starts from a description and finds people you don't know yet.
How long does a search take?
It runs as a background task. The POST returns a task_id at once, and you can read results while the search is still running.
Can I stop a search halfway?
Yes. Pause, resume or cancel the task at any time with POST /desearch/people/tasks/{task_id}/pause, /resume or /cancel.
How do I avoid finding the same people again?
Pass the handles you already have in exclude, up to 1,000 per search. To see everyone across searches in one place, use GET /desearch/people/profiles.
Can I filter TikTok creators by country?
No. TikTok Creator Search has no countries filter. X, YouTube and LinkedIn do.
Does it return private contact details?
No. People Search uses public data only. On YouTube and TikTok it returns a public email when the creator lists one.
How long are results kept?
30 days.
What does it cost?
X Profile Search: $40.00 / 1000 profiles (minimum 5 per search). YouTube Creator Search: $50.00 / 1000 creators (minimum 3). LinkedIn Profile Search: $50.00 / 1000 profiles (minimum 2). TikTok Creator Search: $50.00 / 1000 creators (minimum 2). You pay only for qualified profiles delivered. Confirm current rates in Console.
Get started
- Create an API key in Console.
- Run the cURL request above, or use an SDK. JavaScript:
npm install desearch-js(1.7.0 or later). Python: desearch-py 1.5.0 or later installs from GitHub until PyPI catches up. - Follow the People Search guide for the full task flow, filters and result fields.
Describe the people you want and run your first People Search. New accounts get $5 in API credits after attaching a card in Console, then pay as they go.
Reference: People Search guide