Search records
search_recordsList/filter records of any object type. The right tool for a plain LIST — open tasks, deals in a stage, tasks for one person, contacts at an account — before run_report (counts, sums, grouping, trends, charts). Pass object_type and optional filters (field key → exact value; relationship fields filter by target id; e.g. object_type:"task" with filters:{status:"open"}, object_type:"opportunity" with filters:{stage:"proposal", open_only:true}). Optional free-text query searches by NAME/text on the built-in objects that support it (account, contact, opportunity, lead, task, touch, meeting); for activity (object_type:"touch") it ALSO searches stored EMAIL CONTENT and PARTICIPANT addresses (sender/recipient, attendees), so "sally@acme.com", "kayode" or "acme.com" finds the activity that reached that person. Keyset-paginated, default 20 rows (limit 1–100): pass next_cursor back as cursor. Order varies by object — most newest first, tasks by due date ascending (undated last). Every object type answers in ONE shape: the rows are the top-level records array beside count, object_type, next_cursor, has_more and search_coverage (a built-in object's nested result is retained one release, same rows). Works for custom AND built-in objects (routing to the typed search — its filter keys apply; query is ignored, with a note, where unsupported). For deals of a given TYPE use object_type:"opportunity" with filters:{type:"renewal", open_only:true}; the type as object_type (e.g. "renewal") auto-routes there. Opportunity rows carry each account's reply-recency (account_last_inbound_at / account_last_touch_at), so 'open renewals with no reply in N days' is one call. Unknown or unsupported filter keys/values are IGNORED (echoed in ignored_filters + a note) with search_coverage.status='unsupported_query': those rows DO NOT answer the original query — correct the inputs before claiming matches or none. search_coverage also distinguishes a complete result from one page; follow every next_cursor for an exhaustive answer. An unknown object_type returns the valid types. Unified work queue: object_type:'task', projection:'actions' — sequence steps included, reminder tasks deduplicated, exact counts plus paged rows; filters scope (mine/team/all; assignment, not book), bucket (due/upcoming/paused/completed/all), channel (email/call/linkedin/other), source (task/sequence), sequence or owner UUID, day (YYYY-MM-DD), time_zone (IANA), timed_only. Use each row's taskId/enrollmentId for writes, never its projection id. Nothing is sent.
When to use: Find records of any object (built-in, meeting, or custom). The right tool for a plain list — open tasks, deals in a stage — before reaching for run_report. Filter by field value; keyset-paginated, 20 rows by default; every object type answers with the rows in a top-level records array beside search_coverage. A free-text query searches by name on the objects that support it; for touches it also full-text-searches stored email CONTENT and matches a participant email ('find the emails about X', 'find the emails to sally@acme.com'; matches carry a highlighted snippet).
Example: Find the emails to sally@acme.com.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Page size, 1–100 (default 20). Out-of-range values are clamped. | |
| query | No | Free-text search. Matches names + (for touch/activity) email subject/summary, stored email body content, and participant addresses. Object types without free-text search ignore it (noted in the result). | |
| cursor | No | Opaque keyset cursor: pass the previous page's next_cursor to fetch the next page; omit for the first page (a stale or invalid cursor restarts from page one). | |
| filters | No | Field key → exact scalar value (string / number / boolean). Non-scalar values can't be matched and are ignored with a note. | |
| projection | No | Read-only unified Actions queue, for object_type task. | |
| object_type | Yes | Object key to list — a built-in (account, contact, opportunity, task, touch, meeting, report…), a custom object's key, or an opportunity type key such as renewal (auto-routed). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| count | No | ||
| total | No | ||
| counts | No | ||
| result | No | ||
| records | No | ||
| has_more | No | ||
| projection | No | ||
| next_cursor | No | ||
| object_type | No | ||
| ignored_filters | No | ||
| search_coverage | No | ||
| custom_field_definitions | No |