Skip to main content
Use MCP search to find companies or people, preview the resulting dataset, and continue work that runs asynchronously. Start with the supported-tools guide for the complete schema. Submit a natural-language request to build a company or people dataset. Important inputs: Example:
The completed response usually includes an answer, a session_id, and a dataset_id:

​
For AI agents

  • Call list_accounts when the account is ambiguous and preserve the selected account_id.
  • Call get_credit_balance when the request may use paid research or another credit-consuming mode.
  • Use returned dataset fields instead of guessing field names.
  • Preserve search_handle and agent_run_id; recover existing work before retrying.
  • Preview results before paid follow-up work.
When the account is ambiguous, call list_accounts first and ask the user to select an account. Do not infer an account from a dataset ID, session ID, or run ID. Use mode: "default" for ordinary natural-language audience requests. This is the fastest path for finding companies or people with common criteria such as industry, title, geography, employee count, or other supported filters.

​
Safe search prompt

The assistant should call list_accounts if needed, then search, and inspect the result with get_search_result when a handle is returned. Search and preview are read-only; do not automatically chain them into enrichment, qualification, research, publishing, or downloads.

​
Refine a search with sessions

Reuse the returned session_id when a follow-up should continue the same search conversation. Keep the same account_id and provide a new query:
Do not start an unrelated search when a session is available for the refinement the user requested.

​
Advanced Dataset Creator

Use mode: "research" when the request needs custom logic that is hard to express as fixed filters, including:
  • Custom SQL-style conditions or exact filtering.
  • Aggregations, rankings, counts, or breakdowns.
  • Ratios and comparisons between custom groups.
  • Historical or time-based signals.
  • Explicit output columns such as counts, ratios, booleans, and labels.
Research search uses a two-step approval flow:
  1. Send the request with mode: "research" and preserve the returned session_id.
  2. Review the proposed query, expected result, and credit quote.
  3. After the user approves, call search again with query: "confirm", the same session_id, mode: "research", and account_id.
Do not pass confirm: true; MCP search does not accept that argument.

​
Advanced Dataset Creator examples

Find companies using a custom ratio and request specific output columns:
After reviewing the proposal and receiving approval:
Ask for an aggregation or ranking:
Research mode may return a SQL proposal and credit quote without a dataset on the first turn. Do not treat that response as completed work until the user approves and the confirmation call returns a completed result.

​
Search results and recovery

Search responses can include a dataset identifier, a search handle, or an agent_run_id. Keep every identifier with the selected account. Use get_search_result for a search handle. Use get_agent_run for one agent-run status read, wait_for_agent_run for bounded polling, list_agent_runs to find runs for a session, and get_latest_agent_run when the trigger response was lost. If the response is still running, call get_search_result with the exact opaque handle, the same account_id, and a new wait_seconds value. Do not submit the same query again while it is running. wait_seconds is bounded. A wait expiration does not cancel remote work. See Continue a search or workflow before starting another request. If the trigger response was lost, use list_agent_runs or get_latest_agent_run with the original session_id and agent context to recover it. Once a search completes, use the returned dataset_id for dataset inspection and later workflows. Do not assume the input or previous dataset is the output of a new search.