Which endpoint

Humans

Need a natural-language answer with sources: AI Search (POST /desearch/ai/search).
Need ranked pages, no model summary: plain Search (POST /search). See the API reference.
Need sources without a completion: links endpoints (POST /desearch/ai/search/links/web or POST /desearch/ai/search/links/twitter).
Need keyword SERP / pagination: GET /web.
Need page body from a URL you already have: Extract (GET /web/extract). See the Extract API guide.
Need X operators / posts / replies / trends: X API.
Need TikTok / Facebook / Instagram / YouTube / Reddit / Threads: Social APIs.
Need a list of people or creators who match a description (X, YouTube, LinkedIn, TikTok): People Search.
Need companies that match a description, or contacts and leaders for domains you already have: Company Search (Company Search or Company Enrich).

Agents / tool authors

Route by contract: AI Search when the caller needs completion or multi-tool natural-language retrieval; POST /search for structured ranked hits without a model summary; GET /web for keyword SERP; Extract for URL to content; platform X and social tools when you need post, replies, or trends APIs (not only tools: ["twitter"] inside AI Search); People Search when the caller needs profiles of people who match a description; Company Search when it needs companies that match a description, and Company Enrich when it has domains and needs their public emails, phones, social profiles, and leaders. People Search, Company Search, and Company Enrich run as background tasks: the POST returns a task_id, and the results come from polling the task.

Decision matrix

Use this when…	Path	What you get	Cost cue (no dollar rates)
Natural-language question across sources, plus optional summary or streaming	`POST /desearch/ai/search`	`search[]`, optional `tweets[]` when `twitter` is in `tools`, optional `completion`	Headers `X-Desearch-Cost-Usd`, `X-Desearch-Usage-Count`, `X-Desearch-Service`, `X-Desearch-Currency`; body cost fields on JSON objects
Sources only, no completion (web family)	`POST /desearch/ai/search/links/web`	Link lists per API reference	Links pricing in Console. No dollar figures here
Sources only on the X/Twitter links path	`POST /desearch/ai/search/links/twitter`	Twitter-oriented link results	Links pricing in Console. No dollar figures here
Ranked web pages; no model summary	`POST /search`	Ranked pages. Response shape is on the API reference page, not here	API reference. Dollar rates stay off this page
Keyword SERP-style hits plus pagination	`GET /web?query=…&start=…`	SERP-like hits (`query` and `start` only). `start` is the number of results to skip, any value from 0 to 100	Web Search pricing in Console. No dollar figures here
Text, markdown or HTML for a known URL	`GET /web/extract`	Extracted content	Extract pricing. `js=true` is billed at a higher rate. No dollar figures here
Exact X keyword ops, post, user, replies, or trends	X guide and API reference (`GET /twitter…`)	Posts and metadata	X pricing in Console. No dollar figures here
TikTok, Facebook, Instagram, YouTube, Reddit, or Threads	`POST /desearch/tiktok/search`, `POST /desearch/facebook/search`, `POST /desearch/instagram/search`, `POST /desearch/youtube/search`, `POST /desearch/reddit/search`, `POST /desearch/threads/search`, plus GET helpers in API reference	Platform objects	Social pricing in Console. Guide: Social APIs
People or creators who match a description, on X, YouTube, LinkedIn, or TikTok	`POST /desearch/people/search/{x,youtube,linkedin,tiktok}`, then `GET /desearch/people/tasks/{task_id}/results`	A background task, then scored profiles with the posts or videos behind each match	Billed per person delivered, with a per-search minimum. A search that finds nobody is free. Guide: People Search
Companies that match a description, with their public contacts and leaders	`POST /desearch/companies/search`, then `GET /desearch/companies/tasks/{task_id}/results`	A background task, then scored companies with emails, phones, social profiles, and leaders, each with the page it came from	Billed per company delivered, with a per-task minimum. A task that delivers none is free. Guide: Company Search
Public contacts and leaders for domains you already have	`POST /desearch/companies/enrich`, then `GET /desearch/companies/tasks/{task_id}/results`	A background task, then one company per domain, in the same shape, without a fit score	Billed per company delivered, with a per-task minimum. A task that delivers none is free. Guide: Company Search

AI Search vs plain Search vs links vs SERP

AI Search: one prompt, optional tools, optional completion, optional streaming. Start with the Search API first call.
Links endpoints: sources without a completion, as one JSON object (search_results on web, miner_tweets on twitter). Prefer these when the caller wants that JSON object. ONLY_LINKS on POST /desearch/ai/search returns SSE events with "type": "search" and link objects, not a cost-only JSON body.
Plain POST /search: ranked hits without a model summary. See the API reference. This page does not document a response shape or dollar rates.
GET /web: keyword SERP with query and start pagination. start is the number of results to skip, any value from 0 to 100; a value outside that range returns 422 and is not charged. Each request returns up to 20 results. Use start to get more. The /web endpoint now returns 200 on success and clearer 422 and 503 error codes.

Page content you already have

Use Extract (GET /web/extract) when you already have a URL and need the page body. Legacy GET /web/crawl is a compatibility alias only. To see how Desearch's own crawler identifies itself, read the DesearchBot page.

Social and X

X: follow the X API guide. Inside AI Search, tools: ["twitter"] is not a substitute for operators, replies, or trends APIs.
TikTok, Facebook, Instagram, YouTube, Reddit, and Threads: Social APIs. Do not present a /docs/guide/apis/social-apis URL as live.
YouTube videos, transcripts, comments, and channels; Reddit posts, subreddits, and comment trees; Threads posts, users, and profiles: POST /desearch/youtube/search, POST /desearch/reddit/search, POST /desearch/threads/search, plus the GET helpers on Social APIs. AI Search tools does not take youtube, reddit, or threads.
People rather than posts: People Search returns X profiles, YouTube creators, LinkedIn members, or TikTok creators who match a plain-language description, each with a fit score and the evidence behind it.

Companies

Company Search returns companies, not pages: describe them in plain language (POST /desearch/companies/search), or send the domains you have (POST /desearch/companies/enrich). Each company comes with its public emails, phones, social profiles, and leaders (CEO, founders, CTO, and CFO by default), and every contact keeps the page it came from. Company Search also scores each company against the description.

AI Search `tools[]` (short)

Goal	Prefer
General web evidence	`web`
Reddit threads	`GET /web` with `site:reddit.com` in `query`. For Reddit posts by keyword, use `POST /desearch/reddit/search` (Social APIs)
X posts inside AI Search	`twitter`. Can combine with `web` in one call (`search` + `tweets`). For operators, replies, or trends, use the X API

Supported tools: web, twitter. Other values are unsupported and may be rejected (for example, youtube returns 422).

Search API first call and annotated response
Streaming AI Search
Auth and API keys
API Reference