AI search (Reddit, HN, arXiv, Wikipedia), X and web search, page extraction, X data, People Search.
Call this server's tools from your browser. Nothing to install.
Desearch API key. Send this header, or connect with OAuth and paste the key on the Desearch sign-in page. Discovery does not need a key.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
AI search and analysis on web using Desearch AI
Question, example: 'What is the latest news on AI?'
Model to use for the search: NOVA (default) or ORBIT.
Source ids sent to POST /desearch/ai/search. Short ids: 'web', 'twitter', 'arxiv', 'wikipedia', 'hackernews', 'reddit'. Legacy labels such as 'Web Search', 'ArXiv Search', 'Wikipedia Search', 'Hacker News Search', and 'Reddit Search' are rewritten to those ids. Example: ['web', 'twitter'].
End of the date range in UTC (YYYY-MM-DDTHH:MM:SSZ). Use with start_date.
Start of the date range in UTC (YYYY-MM-DDTHH:MM:SSZ). Use with end_date.
Deprecated relative window; prefer start_date/end_date. Example: 'PAST_WEEK'
ONLY_LINKS returns links only; LINKS_WITH_FINAL_SUMMARY adds an AI summary. Link arrays are kept under whichever key the API uses, along with billing fields. ONLY_LINKS still depends on the API to include those links.
Drop Web Search results from these domains, example: ['pinterest.com']
Restrict Web Search results to these domains, example: ['bbc.com', 'reuters.com']
AI search and analysis on web using Desearch AI
| Argument | Type | Description |
|---|---|---|
| model | string | Model to use for the search: NOVA (default) or ORBIT. |
| tools | array | Source ids sent to POST /desearch/ai/search. Short ids: 'web', 'twitter', 'arxiv', 'wikipedia', 'hackernews', 'reddit'. Legacy labels such as 'Web Search', 'ArXiv Search', 'Wikipedia Search', 'Hacker News Search', and 'Reddit Search' are rewritten to those ids. Example: ['web', 'twitter']. |
| prompt* | string | Question, example: 'What is the latest news on AI?' |
| end_date | string | End of the date range in UTC (YYYY-MM-DDTHH:MM:SSZ). Use with start_date. |
| start_date | string | Start of the date range in UTC (YYYY-MM-DDTHH:MM:SSZ). Use with end_date. |
| date_filter | string | Deprecated relative window; prefer start_date/end_date. Example: 'PAST_WEEK' |
| result_type | string | ONLY_LINKS returns links only; LINKS_WITH_FINAL_SUMMARY adds an AI summary. Link arrays are kept under whichever key the API uses, along with billing fields. ONLY_LINKS still depends on the API to include those links. |
| exclude_domains | array | Drop Web Search results from these domains, example: ['pinterest.com'] |
| include_domains | array | Restrict Web Search results to these domains, example: ['bbc.com', 'reuters.com'] |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"prompt"
],
"properties": {
"model": {
"enum": [
"NOVA",
"ORBIT"
],
"type": "string",
"default": "NOVA",
"description": "Model to use for the search: NOVA (default) or ORBIT."
},
"tools": {
"type": "array",
"items": {
"enum": [
"web",
"twitter",
"arxiv",
"wikipedia",
"hackernews",
"reddit"
],
"type": "string"
},
"default": [
"web",
"twitter"
],
"description": "Source ids sent to POST /desearch/ai/search. Short ids: 'web', 'twitter', 'arxiv', 'wikipedia', 'hackernews', 'reddit'. Legacy labels such as 'Web Search', 'ArXiv Search', 'Wikipedia Search', 'Hacker News Search', and 'Reddit Search' are rewritten to those ids. Example: ['web', 'twitter']."
},
"prompt": {
"type": "string",
"description": "Question, example: 'What is the latest news on AI?'"
},
"end_date": {
"type": "string",
"description": "End of the date range in UTC (YYYY-MM-DDTHH:MM:SSZ). Use with start_date."
},
"start_date": {
"type": "string",
"description": "Start of the date range in UTC (YYYY-MM-DDTHH:MM:SSZ). Use with end_date."
},
"date_filter": {
"enum": [
"PAST_24_HOURS",
"PAST_2_DAYS",
"PAST_WEEK",
"PAST_2_WEEKS",
"PAST_MONTH",
"PAST_2_MONTHS",
"PAST_YEAR",
"PAST_2_YEARS"
],
"type": "string",
"description": "Deprecated relative window; prefer start_date/end_date. Example: 'PAST_WEEK'"
},
"result_type": {
"enum": [
"ONLY_LINKS",
"LINKS_WITH_FINAL_SUMMARY"
],
"type": "string",
"description": "ONLY_LINKS returns links only; LINKS_WITH_FINAL_SUMMARY adds an AI summary. Link arrays are kept under whichever key the API uses, along with billing fields. ONLY_LINKS still depends on the API to include those links."
},
"exclude_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Drop Web Search results from these domains, example: ['pinterest.com']"
},
"include_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Restrict Web Search results to these domains, example: ['bbc.com', 'reuters.com']"
}
},
"additionalProperties": false
}Extract a public URL and return its content as plain text or HTML using Desearch. Preferred over web-crawl for new integrations. API docs: https://www.desearch.ai/docs/api-reference/get-web-extract
| Argument | Type | Description |
|---|---|---|
| js | boolean | Render JavaScript before reading the page. |
| url* | string | Public URL to read, example: 'https://desearch.ai' |
| wait | number | Post-load wait in milliseconds when JavaScript rendering is enabled. |
| format | string | Content format to return: 'html' or 'text'. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url"
],
"properties": {
"js": {
"type": "boolean",
"description": "Render JavaScript before reading the page."
},
"url": {
"type": "string",
"description": "Public URL to read, example: 'https://desearch.ai'"
},
"wait": {
"type": "number",
"description": "Post-load wait in milliseconds when JavaScript rendering is enabled."
},
"format": {
"enum": [
"html",
"text"
],
"type": "string",
"description": "Content format to return: 'html' or 'text'."
}
},
"additionalProperties": false
}Read a public page as text. Pass a URL returned by search.
| Argument | Type | Description |
|---|---|---|
| id* | string | URL of the page to read. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "URL of the page to read."
}
},
"additionalProperties": false
}Everyone your People Searches found on one platform, one entry per person: their best-scoring result and the search that found them (found_by). Free; it does not run a new search. Search by name, handle, bio, or location with q, filter by contact channels (has), audience, fit score, location, or verification, and sort by score, recent, or audience. People from searches that ended more than 30 days ago are left out.
| Argument | Type | Description |
|---|---|---|
| q | string | Text in the name, handle, bio, or location, example: 'skincare'. |
| has | array | Channels every person must have, example: ['email', 'instagram']. 'email' is a public email; the others are a link of that type. |
| sort | string | 'score' (API default), 'recent', or 'audience'. |
| limit | integer | People per page (1-200, default 25). |
| cursor | string | next_cursor from the previous page. |
| location | string | Text in the location, example: 'united states'. |
| platform* | string | Platform: 'x', 'youtube', 'linkedin', or 'tiktok'. |
| verified |
Start a paid job billed to the user's Desearch balance: find people on X, YouTube, LinkedIn, or TikTok who match a plain-language description. Each person comes back with a fit score, why they matched, their audience, and public contacts and links. This call reserves count times the platform's per-person price (reserved_cost_usd) and returns a task_id at once. When the search ends you pay only for the people it delivered (a per-search minimum applies when it finds anyone; a search that finds no one is free) and the rest of the reservation is returned. The search runs in the background, usually for 1 to 5 minutes: poll people-search-status with the task_id to read progress and the people found so far, and use people-search-control to pause, resume, or cancel it. Do not start the same search twice; send idempotency_key so a retry returns the first task instead of charging again. Filters depend on the platform. x: min_followers, max_followers, verified_only, countries, keywords, exclude_keywords. youtube: min_subscribers, max_subscribers, countries, require_contact, keywords, exclude_keywords. linkedin: min_followers, max_followers, countries, keywords, exclude_keywords. tiktok: min_followers, max_followers, require_contact, keywords, exclude_keywords.
| Argument | Type | Description |
|---|---|---|
| count | integer | How many qualified people to find (5-200, API default 25). The search reserves this many and bills only the people it delivers. |
| query* | string | Who you are looking for, in plain language, example: 'Skincare creators who review sunscreen'. |
| exclude | array | Handles to leave out, for example people you already contacted. |
| keywords |
Pause, resume, or cancel a People Search task. Free. pause: a queued search pauses at once; a running one finishes its current batch first (status pausing, then paused). A search paused for more than 7 days is cancelled. resume: continues a paused search where it stopped, with no new charge. cancel: stops the search for good; you pay only for the people it already delivered and the rest of the reservation is returned. People found so far stay readable for 30 days.
| Argument | Type | Description |
|---|---|---|
| action* | string | 'pause', 'resume', or 'cancel'. cancel cannot be undone. |
| task_id* | string | task_id returned by people-search, example: '3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d' |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id",
"action"
],
"properties": {
"action": {
"enum": [
"pause",
"resume",
"cancel"
],
"type": "string",
"description": "'pause', 'resume', or 'cancel'. cancel cannot be undone."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "task_id returned by people-search, example: '3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d'"
}
},
"additionalProperties": false
}Status, progress, and cost of one People Search task, plus a page of the people found so far: name, handle, url, platform, audience, location, fit score, why they matched, contacts, and links. Free. People arrive while the search runs: pass the returned next_cursor as cursor on the next call to get only the people found since then. When done is true and has_more is false you have everyone the search found. An ended task has completion_reason (why it stopped), coverage_limited: true when a budget stopped it before count (more people may match), and warnings such as partial_enrichment (some profiles could not be read, so those people were scored on the search hit; they show enrichment: failed). Each person has fully_verified (every criterion confirmed by their own profile or posts) and unverified_criteria (criteria that are unknown or not met, or a disqualifier that applies). These are information only: the person still qualified.
| Argument | Type | Description |
|---|---|---|
| limit | integer | People per page (1-100, default 25). |
| cursor | string | next_cursor from the previous people-search-status call. Omit to start from the first person. |
| task_id* | string | task_id returned by people-search, example: '3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d' |
| include_people | boolean | Set false to read only the status, progress, and cost. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"task_id"
],
"properties": {
"limit": {
"type": "integer",
"default": 25,
"maximum": 100,
"minimum": 1,
"description": "People per page (1-100, default 25)."
},
"cursor": {
"type": "string",
"maxLength": 64,
"description": "next_cursor from the previous people-search-status call. Omit to start from the first person."
},
"task_id": {
"type": "string",
"format": "uuid",
"description": "task_id returned by people-search, example: '3f1c2b9e-8d4a-4c1e-9b7a-2e5f6a7b8c9d'"
},
"include_people": {
"type": "boolean",
"default": true,
"description": "Set false to read only the status, progress, and cost."
}
},
"additionalProperties": false
}Your People Search tasks, newest first, with status, counts, cost, why each ended search stopped (completion_reason, coverage_limited), and the metadata labels set on people-search. Free. Use it to find a task_id (filter by metadata to find the searches of one campaign), or to see which searches are still queued, running, or paused: a new search is refused while too many are active.
| Argument | Type | Description |
|---|---|---|
| limit | integer | Tasks per page (1-100, API default 20). |
| cursor | string | next_cursor from the previous page. Keep the same metadata filter when you page. |
| status | array | Only tasks in these statuses, example: ['running', 'paused']. |
| metadata | object | Only tasks whose metadata has all of these key/value pairs (exact match, up to 3), example: {"campaign": "q4-outbound"}. |
| platform | string | Only tasks on this platform: 'x', 'youtube', 'linkedin', or 'tiktok'. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Tasks per page (1-100, API default 20)."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page. Keep the same metadata filter when you page."
},
"status": {
"type": "array",
"items": {
"enum": [
"queued",
"running",
"pausing",
"paused",
"cancelling",
"completed",
"partial",
"failed",
"cancelled",
"expired"
],
"type": "string"
},
"description": "Only tasks in these statuses, example: ['running', 'paused']."
},
"metadata": {
"type": "object",
"description": "Only tasks whose metadata has all of these key/value pairs (exact match, up to 3), example: {\"campaign\": \"q4-outbound\"}.",
"additionalProperties": {
"type": "string",
"maxLength": 200
}
},
"platform": {
"enum": [
"x",
"youtube",
"linkedin",
"tiktok"
],
"type": "string",
"description": "Only tasks on this platform: 'x', 'youtube', 'linkedin', or 'tiktok'."
}
},
"additionalProperties": false
}Search the public web and return titles and links. Use fetch with a result URL to read the page.
| Argument | Type | Description |
|---|---|---|
| query* | string | Search query. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Search query."
}
},
"additionalProperties": false
}Crawl a public URL and return its content as plain text or HTML on the legacy Desearch /web/crawl route. The SDK marks webCrawl deprecated in favor of extract; this tool stays for parity with that route. Prefer extract for new integrations. API docs: https://www.desearch.ai/docs/guide/apis/extract-api
| Argument | Type | Description |
|---|---|---|
| js | boolean | Render JavaScript before reading the page. |
| url* | string | Public URL to read, example: 'https://desearch.ai' |
| wait | number | Post-load wait in milliseconds when JavaScript rendering is enabled. |
| format | string | Content format to return: 'html' or 'text'. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"url"
],
"properties": {
"js": {
"type": "boolean",
"description": "Render JavaScript before reading the page."
},
"url": {
"type": "string",
"description": "Public URL to read, example: 'https://desearch.ai'"
},
"wait": {
"type": "number",
"description": "Post-load wait in milliseconds when JavaScript rendering is enabled."
},
"format": {
"enum": [
"html",
"text"
],
"type": "string",
"description": "Content format to return: 'html' or 'text'."
}
},
"additionalProperties": false
}Search the web for links using Desearch. Only the web source is accepted.
| Argument | Type | Description |
|---|---|---|
| count | integer | Results to return per source. Min 10. Max 200. |
| tools | array | Sources to search. Only 'web' is accepted; other ids are rejected before the API call. 'Web Search' is accepted and rewritten to 'web'. Defaults to ['web']. |
| prompt* | string | Search query prompt, example: 'open source browser automation tools' |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"prompt"
],
"properties": {
"count": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"description": "Results to return per source. Min 10. Max 200."
},
"tools": {
"type": "array",
"items": {
"enum": [
"web"
],
"type": "string"
},
"default": [
"web"
],
"minItems": 1,
"description": "Sources to search. Only 'web' is accepted; other ids are rejected before the API call. 'Web Search' is accepted and rewritten to 'web'. Defaults to ['web']."
},
"prompt": {
"type": "string",
"description": "Search query prompt, example: 'open source browser automation tools'"
}
},
"additionalProperties": false
}SERP-style web search using Desearch. Returns ranked titles, links, and snippets.
| Argument | Type | Description |
|---|---|---|
| query* | string | Search query, example: 'latest news on AI' |
| start | integer | How many results to skip for pagination (0, 10, 20, ...). Omit for the first page. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Search query, example: 'latest news on AI'"
},
"start": {
"type": "integer",
"minimum": 0,
"description": "How many results to skip for pagination (0, 10, 20, ...). Omit for the first page."
}
},
"additionalProperties": false
}AI search for X (Twitter) post links using Desearch. Returns links from posts that match the prompt.
| Argument | Type | Description |
|---|---|---|
| count | integer | Results to return. Min 10. Max 200. |
| prompt* | string | Search query prompt, example: 'Bittensor subnet updates' |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"prompt"
],
"properties": {
"count": {
"type": "integer",
"maximum": 200,
"minimum": 10,
"description": "Results to return. Min 10. Max 200."
},
"prompt": {
"type": "string",
"description": "Search query prompt, example: 'Bittensor subnet updates'"
}
},
"additionalProperties": false
}Fetch a single X (Twitter) post by its ID.
| Argument | Type | Description |
|---|---|---|
| id* | string | The unique ID of the post, example: '1234567890' |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The unique ID of the post, example: '1234567890'"
}
},
"additionalProperties": false
}Fetch replies to an X (Twitter) post, with an optional keyword query.
| Argument | Type | Description |
|---|---|---|
| count | integer | Number of posts to retrieve (1-100). |
| query | string | Advanced search query to filter replies. |
| post_id* | string | The ID of the post to fetch replies for. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"post_id"
],
"properties": {
"count": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Number of posts to retrieve (1-100)."
},
"query": {
"type": "string",
"description": "Advanced search query to filter replies."
},
"post_id": {
"type": "string",
"description": "The ID of the post to fetch replies for."
}
},
"additionalProperties": false
}List users who retweeted an X (Twitter) post. Pass cursor to page through more users.
| Argument | Type | Description |
|---|---|---|
| id* | string | The ID of the post to get retweeters for. |
| cursor | string | Cursor for pagination from a previous response. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the post to get retweeters for."
},
"cursor": {
"type": "string",
"description": "Cursor for pagination from a previous response."
}
},
"additionalProperties": false
}Fetch full X (Twitter) posts for a list of post URLs.
| Argument | Type | Description |
|---|---|---|
| urls* | array | Post URLs to fetch, example: ['https://x.com/user/status/123'] |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"urls"
],
"properties": {
"urls": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Post URLs to fetch, example: ['https://x.com/user/status/123']"
}
},
"additionalProperties": false
}Search X (Twitter) posts by a specific user, with an optional keyword query.
| Argument | Type | Description |
|---|---|---|
| user* | string | User to search for, example: 'elonmusk' |
| count | integer | Number of posts to retrieve (1-100). |
| query | string | Advanced search query to filter this user's posts. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"description": "User to search for, example: 'elonmusk'"
},
"count": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Number of posts to retrieve (1-100)."
},
"query": {
"type": "string",
"description": "Advanced search query to filter this user's posts."
}
},
"additionalProperties": false
}Search X (Twitter) using Desearch AI. Optional filters narrow by user, date, language, verification, media, and engagement. Sort stays Top.
| Argument | Type | Description |
|---|---|---|
| lang | string | Language code, example: 'en', 'es', 'fr' |
| user | string | User to search for, example: 'elonmusk' |
| count | number | Number of search results to return (default: 20), max is 100 |
| query* | string | Twitter advanced search query, example: 'from:elonmusk since:2023-01-01 min_replies:10' |
| end_date | string | End date in UTC (YYYY-MM-DD). Use with start_date. |
| is_image | boolean | Include only posts with images. |
| is_quote | boolean | Include only posts that are quotes. |
| is_video | boolean | Include only posts with video. |
| verified | boolean | Filter for verified users. |
Retrieve trending topics on X (Twitter) for a location by its WOEID using Desearch.
| Argument | Type | Description |
|---|---|---|
| count | integer | Number of trends to return (30-100). |
| woeid* | integer | WOEID of the location, example: 23424977 for the United States. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"woeid"
],
"properties": {
"count": {
"type": "integer",
"maximum": 100,
"minimum": 30,
"description": "Number of trends to return (30-100)."
},
"woeid": {
"type": "integer",
"description": "WOEID of the location, example: 23424977 for the United States."
}
},
"additionalProperties": false
}Retrieve a user's X (Twitter) timeline posts by username. Pass cursor to page through more posts.
| Argument | Type | Description |
|---|---|---|
| cursor | string | Cursor for pagination from a previous response. |
| username* | string | Username to fetch posts for, example: 'elonmusk' |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"username"
],
"properties": {
"cursor": {
"type": "string",
"description": "Cursor for pagination from a previous response."
},
"username": {
"type": "string",
"description": "Username to fetch posts for, example: 'elonmusk'"
}
},
"additionalProperties": false
}Fetch posts and replies by an X (Twitter) user, with an optional keyword query.
| Argument | Type | Description |
|---|---|---|
| user* | string | Username of the user to search for, example: 'elonmusk' |
| count | integer | Number of posts to retrieve (1-100). |
| query | string | Advanced search query to filter this user's posts and replies. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"user"
],
"properties": {
"user": {
"type": "string",
"description": "Username of the user to search for, example: 'elonmusk'"
},
"count": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Number of posts to retrieve (1-100)."
},
"query": {
"type": "string",
"description": "Advanced search query to filter this user's posts and replies."
}
},
"additionalProperties": false
}| boolean |
| Only verified accounts. Only X and TikTok people carry a verified flag. |
| min_score | integer | Minimum fit score (0-100). |
| max_audience | integer | Maximum followers (subscribers on YouTube). |
| min_audience | integer | Minimum followers (subscribers on YouTube). |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"platform"
],
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"description": "Text in the name, handle, bio, or location, example: 'skincare'."
},
"has": {
"type": "array",
"items": {
"enum": [
"email",
"website",
"x",
"linkedin",
"instagram",
"youtube",
"tiktok"
],
"type": "string"
},
"description": "Channels every person must have, example: ['email', 'instagram']. 'email' is a public email; the others are a link of that type."
},
"sort": {
"enum": [
"score",
"recent",
"audience"
],
"type": "string",
"description": "'score' (API default), 'recent', or 'audience'."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 200,
"minimum": 1,
"description": "People per page (1-200, default 25)."
},
"cursor": {
"type": "string",
"description": "next_cursor from the previous page."
},
"location": {
"type": "string",
"maxLength": 100,
"description": "Text in the location, example: 'united states'."
},
"platform": {
"enum": [
"x",
"youtube",
"linkedin",
"tiktok"
],
"type": "string",
"description": "Platform: 'x', 'youtube', 'linkedin', or 'tiktok'."
},
"verified": {
"type": "boolean",
"description": "Only verified accounts. Only X and TikTok people carry a verified flag."
},
"min_score": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"description": "Minimum fit score (0-100)."
},
"max_audience": {
"type": "integer",
"minimum": 0,
"description": "Maximum followers (subscribers on YouTube)."
},
"min_audience": {
"type": "integer",
"minimum": 0,
"description": "Minimum followers (subscribers on YouTube)."
}
},
"additionalProperties": false
}| array |
| Words that should appear in their posts, videos, or bio. All platforms. |
| metadata | object | Your own labels for this search, example: {"campaign": "q4-outbound"}. Up to 10 keys; keys are 1-40 characters of a-z, 0-9, '_', '.', '-'; values are strings of up to 200 characters. Returned on the task; filter people-search-tasks by it. The search does not use it. |
| platform* | string | Where to look: 'x' (X profiles), 'youtube' (YouTube creators), 'linkedin' (LinkedIn members), or 'tiktok' (TikTok creators). |
| countries | array | Countries to prefer, example: ['US', 'GB']. x, youtube, linkedin. |
| min_score | integer | Only return people with at least this fit score (0-100). |
| max_followers | integer | Maximum follower count. x, linkedin, tiktok. |
| min_followers | integer | Minimum follower count. x, linkedin, tiktok. |
| verified_only | boolean | Only verified or X Premium accounts. x only. |
| idempotency_key | string | Any unique string for this search, for example a UUID. Sending the same key again returns the first task and is not charged again. |
| max_subscribers | integer | Maximum subscriber count. youtube only. |
| min_subscribers | integer | Minimum subscriber count. youtube only. |
| require_contact | boolean | Only creators with a public email (tiktok: in the bio; youtube: an email or contact link). youtube, tiktok. |
| exclude_keywords | array | Leave out people who mention these words. All platforms. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"platform",
"query"
],
"properties": {
"count": {
"type": "integer",
"maximum": 200,
"minimum": 5,
"description": "How many qualified people to find (5-200, API default 25). The search reserves this many and bills only the people it delivers."
},
"query": {
"type": "string",
"maxLength": 1000,
"minLength": 3,
"description": "Who you are looking for, in plain language, example: 'Skincare creators who review sunscreen'."
},
"exclude": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"maxItems": 1000,
"description": "Handles to leave out, for example people you already contacted."
},
"keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 20,
"description": "Words that should appear in their posts, videos, or bio. All platforms."
},
"metadata": {
"type": "object",
"description": "Your own labels for this search, example: {\"campaign\": \"q4-outbound\"}. Up to 10 keys; keys are 1-40 characters of a-z, 0-9, '_', '.', '-'; values are strings of up to 200 characters. Returned on the task; filter people-search-tasks by it. The search does not use it.",
"additionalProperties": {
"type": "string",
"maxLength": 200
}
},
"platform": {
"enum": [
"x",
"youtube",
"linkedin",
"tiktok"
],
"type": "string",
"description": "Where to look: 'x' (X profiles), 'youtube' (YouTube creators), 'linkedin' (LinkedIn members), or 'tiktok' (TikTok creators)."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 20,
"description": "Countries to prefer, example: ['US', 'GB']. x, youtube, linkedin."
},
"min_score": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"description": "Only return people with at least this fit score (0-100)."
},
"max_followers": {
"type": "integer",
"minimum": 0,
"description": "Maximum follower count. x, linkedin, tiktok."
},
"min_followers": {
"type": "integer",
"minimum": 0,
"description": "Minimum follower count. x, linkedin, tiktok."
},
"verified_only": {
"type": "boolean",
"description": "Only verified or X Premium accounts. x only."
},
"idempotency_key": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Any unique string for this search, for example a UUID. Sending the same key again returns the first task and is not charged again."
},
"max_subscribers": {
"type": "integer",
"minimum": 0,
"description": "Maximum subscriber count. youtube only."
},
"min_subscribers": {
"type": "integer",
"minimum": 0,
"description": "Minimum subscriber count. youtube only."
},
"require_contact": {
"type": "boolean",
"description": "Only creators with a public email (tiktok: in the bio; youtube: an email or contact link). youtube, tiktok."
},
"exclude_keywords": {
"type": "array",
"items": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"maxItems": 20,
"description": "Leave out people who mention these words. All platforms."
}
},
"additionalProperties": false
}| min_likes | integer | Minimum number of likes. |
| start_date | string | Start date in UTC (YYYY-MM-DD). Use with end_date. |
| min_replies | integer | Minimum number of replies. |
| min_retweets | integer | Minimum number of retweets. |
| blue_verified | boolean | Filter for blue-checkmark verified users. |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"query"
],
"properties": {
"lang": {
"type": "string",
"description": "Language code, example: 'en', 'es', 'fr'"
},
"user": {
"type": "string",
"description": "User to search for, example: 'elonmusk'"
},
"count": {
"type": "number",
"default": 20,
"description": "Number of search results to return (default: 20), max is 100"
},
"query": {
"type": "string",
"description": "Twitter advanced search query, example: 'from:elonmusk since:2023-01-01 min_replies:10'"
},
"end_date": {
"type": "string",
"description": "End date in UTC (YYYY-MM-DD). Use with start_date."
},
"is_image": {
"type": "boolean",
"description": "Include only posts with images."
},
"is_quote": {
"type": "boolean",
"description": "Include only posts that are quotes."
},
"is_video": {
"type": "boolean",
"description": "Include only posts with video."
},
"verified": {
"type": "boolean",
"description": "Filter for verified users."
},
"min_likes": {
"type": "integer",
"minimum": 0,
"description": "Minimum number of likes."
},
"start_date": {
"type": "string",
"description": "Start date in UTC (YYYY-MM-DD). Use with end_date."
},
"min_replies": {
"type": "integer",
"minimum": 0,
"description": "Minimum number of replies."
},
"min_retweets": {
"type": "integer",
"minimum": 0,
"description": "Minimum number of retweets."
},
"blue_verified": {
"type": "boolean",
"description": "Filter for blue-checkmark verified users."
}
},
"additionalProperties": false
}