Learn and master Clay with Clay university

Next, you'll learn to fix a segment with the Clay CLI, find your way around an audience, and filter a people search down to the companies you already chose.

🛠️ Fixing a Segment from the CLI

Something unexpected happened at the end of the last lesson. The search results didn't save into their own segment. We made a manual segment called U.S PE companies to hold just the PE firms we found, but its filter showed nothing. Without it, we'd risk acting on every company in our audience: tech companies, retail companies, and everything else from past work.

It's a good excuse to troubleshoot with the CLI.

Setting Up the CLI

Find API and CLI in the left sidebar. Run the setup command from that page in your terminal, and the Clay plugin becomes available in the agent you use, whether that's Codex, Claude Code, or something else.

You should aim to get really good at using the CLI, and that means troubleshooting as much as prompting.

The Prompt

Back in the same Claude session as the search:

I went ahead and used the company search that you gave me, and then I went ahead and built a workflow that added every single one of those records to an audience. Can you help me build a segment that contains just those records? I have one right now named "USPE companies", but the filter isn't working because I'm guessing that I did it incorrectly. Go ahead and make the filters for me, please.


You know what you want, and you know what a good result looks like. Let the AI do the rest.

What Claude Found

• Why it showed nothing: the old filter looked for the workflow ID in activity records. Writing records into an audience doesn't create activities, so it couldn't match anything.
• The fix: every record keeps a system field called Workflows that lists the workflows that wrote to it. The new filter is Field: Workflows · Operator: contains · Value: the workflow's ID.
• Why that field: Source only counts records the workflow created. Workflows also catches companies that were already in Audiences before the workflow touched them.

Then check the work in Clay. Open the segment and read its filter. Workflows contains the workflow's name, and the segment holds 2,851 companies, exactly what the workflow added. It's an accidental but useful example of how to use the CLI, Audiences, and troubleshooting together.

⭐ Have you checked out the Clay community? → If fixing things from the terminal is the part you enjoyed, the people doing the most of it are in the Clay community, and Clay Clubs are where they meet up locally to show each other what they built.

🗺️ A Tour of an Audience

Companies and People audiences look almost the same. The difference is the type of data each one syncs.

The Left Menu

• All records: every company or person in your entire universe of prospects
• Segments: the slices of that data you've built and acted on
• Data hub: analytics on your fields, your workflows, signals, and Account Agents. On a mature workspace, this is where you see value build up over time
• Reporting: summary-level data across all your audiences

The Right Menu

• Records: every record, the default view
• Sources: where records came from, like your CRM or a CSV upload
• Exports: every export you've run, saved in one place

Acting on a Segment

From any segment you can:

• Enrich, which opens a new tab straight into a workflow. Think of an enrichment as a workflow node.
• Send, an export action that can go to a workflow or an ad platform
• Add signals

♾️ Segments Are Always On

Every audience, search, and segment is always on. Any new company or person who matches your logic is picked up and acted on by every downstream step you've built, as long as the play still makes sense. No more scheduling specific tables or specific runs. It's one of the most overlooked parts of the new platform.

👥 Filtering People to Your Target Companies

The last lesson only ran the company search. Here's the people side:

1. Open Find Leads → People and paste in the people query from the search skill.
2. Open the filters and check the work. Country is the United States, the industries match, and the job titles make sense. Company and people attributes now live in one unified view, along with derived data points Clay adds with AI.
3. Select the segment of target companies under the company filters, and point it at U.S PE companies.

The count went up slightly, but the list got more accurate, because every person is now tied to a company that fits the play. Don't let the AI do all of the work for you: the query had no link to our segment until we added it by hand.

🚀 What's Next

You can now troubleshoot a segment from the CLI, read your way around an audience, and tie a people search to your target companies.

Next, we'll enrich those companies and people with workflows built from the CLI.