Skip to main content
Use search_buyers for people and company attributes. Use search_signals for activities, event dates, pages, UTM parameters, and click IDs. Examples on this page are tool arguments, not REST request bodies. A custom agent sends them as the arguments of an MCP tool call. Some clients add a namespace to the tool name in their interface; the server names are search_buyers and search_signals.

​
Choose the right timestamp

The signal_at filter maps to the signal’s public captured_at timestamp. A signal can occur before its buyer or signal record is created. Filtering buyers by creation date and filtering signals by occurrence date can therefore return different sets of buyers. For calendar periods, choose a time zone and convert its boundaries to RFC 3339 timestamps. Account for daylight saving time. Prefer a start-inclusive, end-exclusive range using gte and lt. For example, October 19, 2026 in America/Los_Angeles runs from 2026-10-19T07:00:00Z up to, but not including, 2026-10-20T07:00:00Z:
These are illustrative dates. Replace them with the boundaries for your report.

​
Rules and groups

A rule has field, operator, and value. Set a group’s match to all for AND or any for OR. The default is all. The exposed input schema supports a top-level group containing rules and nested groups of rules. This buyer search requires an ICP match and accepts either of two seniorities:
search_buyers accepts an optional filter. search_signals requires a filter with at least one rule. Narrow large searches by date and relevant fields before retrieving pages.

​
Operators and value formats

Use booleans for has_* and is_* fields. Dates must be RFC 3339 timestamps. Use each field only with the operators listed below. For text such as industry, title, or company name, use the data’s wording. industry and company_location equality and membership matches are case-insensitive. If the exact text is unknown, use contains where supported.

​
Buyer filter reference

​
Enumerated buyer values

  • attribution_type: ai, direct, email, in_market, organic, paid, social.
  • seniority: c_suite, director, entry, founder, head, intern, manager, owner, partner, senior, vp.
  • attribution_source: bing, chatgpt, claude, competitor_intent, copilot, customer_marketing, direct, duckduckgo, facebook, gemini, google, google_ads, instagram, linkedin, linkedin_ads, linkedin_comment, linkedin_follow, linkedin_reaction, meta_ads, microsoft_ads, newsletter, nurture, other, outbound, perplexity, product_intent, quora_ads, reddit, reddit_ads, tiktok_ads, topic_intent, transactional, x, x_ads, yahoo, youtube.

​
Signal filter reference

​
Signal types and triggers

When you use a type-specific field or trigger, include a compatible signal_type rule in the top-level group and set that group’s match to all. Putting the type rule only inside an OR subgroup does not satisfy this requirement. For example, website form submissions in the last seven days:
Signal search does not expose attribution_type or attribution_source as filters. For website activity attribution, retrieve the appropriate website signals and inspect website.attribution, website.utm, and website.click_ids. Buyer attribution is available as buyer search filters, but a buyer’s attribution does not describe every later visit.

​
Pagination and totals

Search and list payloads include total, data, and next_cursor. Search payloads also echo applied_filter. Clients may display the payload as parsed JSON or inside MCP content blocks. The following example is illustrative:
  1. Read total for the full matching count; it is not the current page length.
  2. Use data for the current page.
  3. If next_cursor is present, pass it unchanged as cursor with the same tool, filter, and sort order.
  4. Stop when the server returns no continuation cursor.
Do not decode, edit, or reuse a cursor for another query. Search page sizes default to 25; list page sizes default to 100. Set a smaller limit when you need only a few examples. The tool schemas do not advertise a maximum page size. For a count of distinct buyers with activity, a signal total is insufficient: several signals can reference one buyer. Retrieve the necessary signal pages, deduplicate buyer_id, and use get_buyer for the buyer details. For large ranges, narrow the scope; do not label the signal total as a unique-buyer count.

​
Sorting and query size

Buyer and signal searches accept sort_order: desc for newest first (the default) or asc for oldest first. They do not expose a selectable sort_by field or an aggregation/ranking argument. Do not claim a revenue ranking, a full source breakdown, or a unique-buyer total from one sample page. If the server returns query_timeout, narrow the dates or other conditions before retrying.