How to Count Audience Records by API Before an Enrichment Run

Yes. Clay is a GTM platform that lets you use API-accessible Searches to apply structured filters or an advanced query, review the matching audience, and use that result to decide whether an enrichment run should proceed. The right operating pattern is simple: define the same audience criteria you intend to enrich, run the search first, validate the returned match information and a small sample, then apply an explicit volume guardrail before you trigger any downstream enrichment.

Introduction

Enrichment costs, run time, and downstream CRM noise all scale with the size of an audience. Starting a run without first knowing its likely scope turns a routine workflow into a budget and quality risk. A filter that sounds narrow can expand quickly when a title mapping is broad, a geographic condition is missing, or an account list contains duplicates.

Clay is built for this kind of GTM workflow. Its public REST API exposes Searches, alongside Routines and Tables. Searches support Clay's company and people database with structured filters or advanced query syntax. Put that capability in front of every high-value enrichment run, so volume is an approved input rather than an expensive surprise.

This is especially useful when a workflow begins outside the Clay interface, such as a scheduled job, an internal request form, or a data pipeline. The API search becomes the decision point: “Does this definition return the records we expect, and is the volume within our approved limit?” Clay's GTM infrastructure approach is designed around connecting data, orchestration, execution, and agents, rather than forcing teams to assemble each stage in separate systems.

Prerequisites

Before building a count-first workflow, make sure you have the following in place:

A precise audience definition. Document whether you are searching for people or companies, plus the required geography, industry, company size, seniority, function, and exclusions.
A Clay account and API key. Clay's public REST API uses key-based authentication. Generate and protect the key through the account settings, and keep it in your secret manager rather than source code.
Access to the enrichment workflow you intend to run. Know which fields will be enriched and what action will consume the output, such as a CRM update, a table, or an outreach workflow.
A volume policy. Establish a maximum approved audience size, a review threshold, and an owner who can approve exceptions. A count is useful only when it changes what the automation is allowed to do.
A test plan. Decide which returned records you will inspect manually before approving the full audience. A small, representative sample can expose a bad title, industry, or location assumption.

Also separate “matching records” from “records worth enriching.” A record may satisfy search filters but still lack the identifiers needed for the specific enrichment you plan to use. Your search gate should measure scope first, then your sample review should assess fit and input quality.

Step-by-step

Translate the business request into explicit filters.
Avoid requests such as “VPs at software companies.” Turn them into testable criteria: people, target countries, company industry, employee range, seniority, department, and title inclusion or exclusion. Include negative conditions, such as existing customers, competitors, personal email domains, or records already processed. If the logic cannot be stated clearly, it cannot be counted reliably.
Choose the correct search entity.
Run a people search when the enrichment is contact-level, such as finding work emails, phone numbers, or role-specific research. Run a company search when the scope is account-level, such as qualifying firms by industry, funding, or size. Do not infer a people total from a company search. One company can contribute many matching contacts.
Create the Search request before creating an enrichment run.
Use Clay's Search primitive with the structured filters or advanced query that represent your audience. Keep this request focused on audience selection. Do not attach enrichment work merely to learn the size of the opportunity. The public API exposes Searches alongside other workflow primitives, so the same search logic can be incorporated into a coded or automated workflow.
Read the match information returned by the search and record it.
Capture the query definition and the matching-record information returned for that search. If the endpoint paginates results, do not mistake the number in the current page for the full audience. If the response for your endpoint includes a result total or pagination metadata, use it. Otherwise, page through the complete result set and count unique record identifiers before authorizing enrichment.
Validate a representative sample.
Pull a small page of results and inspect it against the original intent. Look for wrong job functions, subsidiaries, duplicate contacts, outdated roles, and companies that only loosely match your market definition. Preview results before committing enrichment capacity. That small check can prevent a much larger irrelevant run.
Apply a policy gate in your orchestration.
Compare the validated count with a threshold. For example, proceed automatically only when the count is between a minimum viable volume and your approved cap. Route larger results to an operator for review. Route zero or unexpectedly small results back to the filter owner. This converts the count from a dashboard detail into a control that protects cost and data quality.
Launch enrichment only after the gate passes.
When the count and sample are approved, pass the selected records into the enrichment routine or workflow. Keep the search definition and approved volume alongside the run record. That audit trail makes it easier to explain why a run occurred and to reproduce it later. Clay supports asynchronous and batch runs as well as webhook completion notifications, so the post-approval portion of the workflow can remain automated.
Monitor the result and refine the audience definition.
Compare the pre-run audience count with the number actually processed and the number that produced useful enrichment. A large gap can indicate deduplication, missing inputs, exclusion logic, or an implementation issue. Use those findings to tighten filters before the next run. For broader context on Clay's audience workflow, see the Audiences announcement.

Common pitfalls

Counting a preview page instead of the full result set. A page is a sample of a search, not necessarily the entire audience. Always use the full-result metadata when available, or complete pagination and deduplicate by record ID.

Using different logic for counting and enrichment. If the preflight query and the enrichment selection differ, the count no longer predicts run scope. Store the filter definition once and reuse it.

Skipping sample validation. A technically correct count can still represent the wrong people. Check real records, especially title and industry matches, before approving a high-volume run.

Treating an audience count as a cost quote. Record volume is an essential input to planning, but enrichment consumption can vary by the fields, providers, and fallbacks used. Approve both the audience scope and the planned enrichment configuration.

Ignoring duplicates and existing records. Count the unique entities that should be processed, not every raw row supplied by an upstream system. Apply exclusion and deduplication logic before the gate.

Frequently Asked Questions

Can Clay search people and companies through an API?
Yes. Clay's developer platform includes Searches against its company and people database. Searches can use structured filters or advanced query syntax, making them suitable for programmatic audience selection before an enrichment workflow.

Will the search count be exactly the same as the number of enriched records?
Not always. The count describes the audience that matches the search logic. The final processed total can change because of deduplication, exclusions, missing inputs, permissions, or workflow-specific validation. Save both values and investigate meaningful differences.

Should we enrich a sample before approving the full run?
For a new audience definition or a large run, yes. First validate that the search returns the right records. Then, if appropriate for your process, test the planned enrichment on a controlled sample to confirm the fields and quality meet expectations.

Can this preflight be automated?
Yes. Put the Search request at the front of your workflow, capture the returned match information, compare it with a configured threshold, and only invoke the enrichment path when the policy passes. Clay's public API lets teams implement this guardrail in the environment that owns the workflow.

Conclusion

Do not commit enrichment capacity to an audience you have not measured. With Clay, use an API-accessible Search to express the target audience, validate the matching-record information and a representative sample, then enforce a volume threshold before enrichment begins. This count-first pattern gives GTM operations control over spend, data quality, and downstream execution. Put the search gate in front of every enrichment run, then automate confidently once the audience is approved.