Frequently asked questions
Short answers to common Desearch API questions. Each answer links to the guide that has the full details.
What is Desearch?
Desearch is one API for web, social, and AI-assisted search. Use it when your product or agent needs current information from the web, X, TikTok, Facebook, Instagram, and other supported sources instead of stale training data. You can reach it through Desearch Console, the REST API, and SDKs and integrations for Python, JavaScript and MCP.
Full details: Desearch overview
How do I get an API key and authenticate?
Create an account in Desearch Console, open API Keys, create a key and copy it once. Store it as DESEARCH_API_KEY on your server and send the raw key in the Authorization header on every request. Keep keys server-side: do not put them in frontend bundles, mobile apps or public repos.
Full details: Desearch overview
Which Desearch endpoint should I use?
Use Search (POST /search) for web pages, with summary: true when you want a short answer with citations. Use AI Search (POST /desearch/ai/search) for X posts, or X posts and web results together, with an optional summary. Use GET /web for keyword SERP results with pagination, and Extract (GET /web/extract) for the page body of a URL you already have. For people, companies or new items on a schedule, use People Search, Company Search or Monitors.
Full details: Which endpoint
How much does the Desearch API cost?
Desearch is pay as you go: Search is $0.30 per 1,000 results with the summary at no extra charge, AI Search is $0.40 per 1,000 items, Web Search is $1.00 per 1,000 searches, Extract is $0.50 per 1,000 pages and X Search is $0.15 per 1,000 posts. Each API has its own billing unit. Rates for People Search, Company Search and Monitors, with the date of each rate, are on https://www.desearch.ai/pricing. Confirm current rates in Console.
Full details: Pricing
Do new accounts get starting credits?
Yes. New accounts get $5 in API credits after attaching a card in Console, then pay as they go.
Full details: Pricing
How do I see what each request cost?
Billable API responses expose the exact request cost in USD. JSON object responses include the cost_usd, usage_count, service and currency fields, and compatible charged responses also carry the same values in the X-Desearch-Cost-Usd, X-Desearch-Usage-Count, X-Desearch-Service and X-Desearch-Currency headers. JSON arrays, text/plain responses such as Extract output, and streaming responses carry the cost in the headers only. Desearch Console shows transaction history, request-cost breakdowns and usage by API key and service.
Full details: Pricing and Billing
How are X searches charged?
X Search (GET /twitter) is billed per unique post returned, never more than the count you request, with no minimum. A search that finds no posts is not charged. Other X search endpoints, such as replies, are billed per post returned with a minimum of 10 posts per request, never more than the count you request; on GET /twitter/replies and GET /twitter/replies/post, a search that finds no posts is not charged. GET /twitter/user/posts is billed per page for the unique posts it returns, with a minimum of 10 posts and at most 60 posts per page, and a page with no posts is not charged. GET /twitter/urls charges each unique post returned, with no minimum. Confirm current rates in Console.
Full details: Pricing
How do I search X posts from a date range or get the newest posts?
Call GET https://api.desearch.ai/twitter with start_date and end_date. Each takes a YYYY-MM-DD date, read in UTC, or an ISO 8601 date-time with a time zone. The default sort is Top, so set sort=Latest when you want the newest posts first. Set count to the number of posts you want; it defaults to 20.
Full details: X Search API reference
What are the rate limits?
Rate limits are enforced per API key on three windows: per minute, per day and per month, and the first limit reached applies. Your key's limits and usage are shown in Console. When you hit a limit, the API returns 429 Too Many Requests: back off and retry. Higher limits are an account change, not a code change: contact the Desearch team.
Full details: Rate limits & errors
What do the API error codes mean?
400 is a malformed request. 401 means a missing or invalid API key. 402 means out of credits: top up in Console. 403 can mean the request was rejected by token or origin checks: send the full API key from Console, copied exactly. 422 means valid auth with invalid parameters: compare your request against the API Reference. 429 means the rate limit was exceeded: retry with exponential backoff. A 5xx is a server-side failure: retry once after a short delay and check status.desearch.ai.
Full details: Rate limits & errors
Can AI Search stream its answer?
Yes. POST /desearch/ai/search streams its summary over server-sent events (SSE) when you set "streaming": true. The OpenAPI default for streaming is true, so always set the boolean explicitly, and use "streaming": false when your client expects one JSON body. The official SDKs currently force non-stream, so call REST to stream. POST /search is not streamed. Read the request cost from the response headers, not the stream body.
Full details: Streaming
How do I get the content of a web page?
Use Extract (GET https://api.desearch.ai/web/extract). Fetch a public URL and get its content back as text, markdown or HTML. Each call fetches the current version of the page, not a cached snapshot. GET /web/crawl is a deprecated alias for GET /web/extract: use /web/extract for new integrations.
Full details: Extract API
Can I use Desearch over MCP?
Yes. Desearch MCP is available over hosted Streamable HTTP at https://mcp.desearch.ai/mcp. Create an API key in Console, then add the server in your agent, for example in Claude Code: claude mcp add --transport http desearch https://mcp.desearch.ai/mcp --header "Authorization: ${DESEARCH_API_KEY}". Confirm the tools from the live tools/list, because the inventory can change.
Full details: MCP
Is there a Python or JavaScript SDK?
Yes. Install the Python SDK with pip install desearch-py and the JavaScript SDK with npm install desearch-js. desearch-js requires Node.js 20.18.1 or later.
Full details: SDKs and tools overview
How do People Search and Company Search work?
Both run in the background. You start a task with one POST, poll it, read the results, and can download them as CSV. A People Search usually takes 1 to 5 minutes. Both bill per result delivered, not per request: starting a task reserves the count you ask for (one company per domain for Company Enrich), you never pay more than the reservation, and the rest of the reservation is returned automatically. With a max_cost_usd budget, the whole budget is reserved. If the search completes or is cancelled while it runs, its search effort (what the search cost, with a margin) is billed up to the budget when the results delivered do not cover it. A search cancelled while queued or paused, or a failed or partial search, pays only for what it delivered. Polling, reading results and exports are free.
Full details: People Search API
What is a monitor?
A monitor is a search that runs on a schedule and returns only what is new since its last run. Creating, reading and changing monitors is free. Each run pays for the searches it makes, at their list price, plus a small screening fee per new item.
Full details: Monitors API