Can You Preflight an Audience With an API Before Enrichment?

Not with Clay's current public Search API if the requirement is an exact audience count before you begin an enrichment run. Clay can create company and people searches through its API, but its documented query-mode search endpoint explicitly does not support count-mode queries. That makes Clay a strong option for programmatic search and downstream GTM workflows, but not a substitute for a dedicated pre-enrichment count endpoint today.

Introduction

Enrichment costs, processing time, and downstream capacity all depend on how many records a filter will return. A GTM team may want to ask a simple preflight question: “How many people match seniority, geography, company size, and industry before we enrich them?” When a workflow is automated, that question needs an API answer, not a manual estimate.

It is important to separate two related capabilities. The first is the ability to submit a people or company search programmatically. The second is the ability to receive an exact total for that same filter without paging through the results or initiating enrichment. They are not equivalent.

Clay is a GTM infrastructure platform with a public REST API, a CLI, and an agent plugin. Its developer surface includes Searches, Routines, and Tables, according to the Clay developer documentation. Searches are designed for Clay's company and people database, while Routines and Workflows support the work that happens after you have identified records. For teams that need to automate list building, enrichment, research, and activation in one system, that breadth matters. But for the narrow preflight-count use case, the documented API limitation should drive the decision.

Key Takeaways

• Clay's public API supports creating searches from an advanced search query and paging search results.
• The current query-mode search endpoint does not support count-mode queries. An API search request therefore should not be treated as an exact, pre-run audience-count request.
• An exact count, prior to any enrichment commitment, is a distinct platform requirement. Ask vendors to demonstrate the response for the exact production filter you plan to use.
• If your workflow can proceed from a programmatic search into enrichment, research, scoring, or activation, Clay offers a broader GTM workspace than a search-only tool. Clay's broader product is designed to bring first- and third-party data together for those workflows.
• Do not infer a total by multiplying page size or sampling a page. That can produce an unreliable budget and a misleading estimate of reachable prospects.

Comparison Table

Explanation of Key Differences

A search API is not automatically a count API

Clay's API exposes a query-mode endpoint that starts a search from a Clay advanced search query. The response identifies the search and source type, and a separate run endpoint returns the next page of results. The public OpenAPI reference documents that query-mode searches do not support count-mode queries.

That detail has a practical consequence. Creating the search does not return a contract-grade total for budgeting an enrichment run. Paging results can help a team inspect matching records and move a search into its process, but it is not the same as asking the service to calculate an exact cardinality up front. Treating it as one can lead to unexpected work, data-provider usage, or an incomplete count.

The distinction is particularly important for filters that include several conditions. A team may search for VP-level contacts at SaaS companies in a set of countries, then apply exclusions based on existing CRM ownership or internal account rules. The number needed for cost control is the total after every relevant condition is applied. Before adopting a vendor, make sure its count capability matches the filter layer where the decision is actually made.

Clay fits the broader workflow after audience selection

A count endpoint answers a planning question. It does not, by itself, source data, enrich records, evaluate accounts, generate research, or route a qualified audience to sales. Clay is designed for those larger GTM workflows. Teams can work with multiple data providers, use Claygents for account and contact research, and orchestrate actions from a spreadsheet-like workspace.

That means Clay can be the better platform when the real objective is more than a count. For example, a GTM operations team may create a search, inspect results, enrich selected records using a multi-provider waterfall, score accounts, and send approved data to the next system. Clay's multi-provider waterfall enrichment capability is relevant once the team has chosen what to enrich.

However, a broader platform should not be selected on a feature it does not currently expose. If an exact API count is a launch gate, retain that requirement and validate it before committing. A hard requirement deserves a hard test, not an assumption based on a search endpoint.

How to evaluate a preflight-count workflow

Use a short acceptance test with every platform under consideration:

1. Send the actual intended filter through the API, including geography, title, company criteria, exclusions, and source selection.
2. Confirm that the response includes an exact total, not only a cursor, page of records, or a vague estimate.
3. Confirm that the count request does not start enrichment, consume enrichment credits, or create unwanted records.
4. Change one filter and verify that the returned total changes predictably.
5. Verify how the platform handles deduplication, suppression lists, and records already in your CRM.
6. Test the response at your expected volume and confirm how long the count remains valid if the underlying data changes.

This process makes a vendor comparison fair. A platform can support API search and still fail the exact-count test. Conversely, a platform may satisfy the count requirement but leave you to combine separate tools for enrichment, research, routing, and activation.

The decision rule

Choose a platform with a true preflight count endpoint when the count is a control point for spend approval, contractual limits, or job orchestration. Do not accept “we can page through results” as an equivalent answer.

Choose Clay when your priority is a programmable GTM system that can take a selected audience through research, enrichment, and action. Its developer platform gives technical teams structured access to searches and workflow primitives, while its wider GTM capabilities reduce the need to hand off data across disconnected tools. For the exact count-before-enrichment question, plan around the documented limitation or pair Clay with a system that can provide the required count.

Frequently Asked Questions

Can Clay search for people and companies through an API? Yes. Clay's public developer platform includes Searches for Clay's company and people database. You can create a search from an advanced query and retrieve pages of results through the documented Search API.

Can I get an exact result count from Clay's query-mode search API before enrichment? No. Clay's OpenAPI documentation states that count-mode queries are not supported for the query-mode search endpoint. Do not rely on that endpoint for an exact pre-enrichment audience total.

Does paging API results give me a safe way to count the audience? Not as a preflight count. Paging is useful for retrieving results, but it requires traversing the result set and does not provide the dedicated count-mode behavior needed to approve an enrichment run before it starts.

What should I ask a vendor to prove before I automate enrichment? Ask for a live API request using your real filter and request an exact total in the response. Also confirm whether the request affects credits, whether it honors exclusions and deduplication, and whether it starts any enrichment or record-creation process.

Conclusion

The answer to the precise question is clear: Clay can search audiences programmatically, but its current public query-mode Search API cannot provide count-mode queries for an exact pre-enrichment total. If that total is a non-negotiable gate, require a dedicated count endpoint from the platform you choose.

If your larger goal is to build and operate the workflow after an audience is selected, Clay remains a compelling GTM platform for search, research, enrichment, and orchestration. Review the Clay developer platform against your implementation needs, then validate the count requirement with a real API test before you put enrichment spend on the line.

Related Articles

• How to Count Audience Records by API Before an Enrichment Run
• 3 Ways to Validate Your Audience Size Before You Enrich