# Upsert Audience > Create an audience or update its name, folder, description, and notes. Free to call; ingesting records consumes data credits. **Date:** 2026-09-25 **Source:** https://gtm.ai/docs/mcp/tools/upsert-audience --- ## Overview An audience is a durable, named dataset in ZoomInfo: accounts or contacts, with columns you define and rows you load. Upsert Audience creates one from an agent. It also renames or reorganizes one that already exists. Every audience workflow starts here. Describe the accounts or people you want, and your AI saves them as an audience your team can enrich, score, and work from. Discovery still comes first: a search-driven audience starts from [Search Companies](/docs/mcp/tools/search-companies) or [Search Contacts](/docs/mcp/tools/search-contacts), and an existing audience is found with [Browse Audiences](/docs/mcp/tools/browse-audiences). ## What You'll Get An audience record: `id`, name, type, folder, description, notes. Everything downstream needs that id. On create with search criteria attached, a job pulls every matching ZoomInfo record into the audience, and each row arrives with the baseline company or contact fields described under [Manage Audience Rows](/docs/mcp/tools/manage-audience-rows). ## Best For - Standing up a prospecting list from ZoomInfo search criteria - Creating an empty audience to load your own records into - Renaming an audience or moving it between folders - Updating the description or notes so the team knows what a dataset is for To load records into an audience, use [Manage Audience Rows](/docs/mcp/tools/manage-audience-rows); to add columns, [Manage Audience Columns](/docs/mcp/tools/manage-audience-columns); to find an existing audience's `id`, [Browse Audiences](/docs/mcp/tools/browse-audiences). To run enrichment and finish the workflow, open the audience in ZoomInfo. ## How It Works Two paths, chosen by whether you pass an `audienceId`: **Create.** Omit `audienceId` and provide `name`, `type` (CONTACT or COMPANY), and `agentInstruction`; `folderId` is optional. **Update.** Provide `audienceId` and `agentInstruction`. Any of `name`, `folderId`, `description`, and `notes` you omit keep their current values. The create response returns the audience `id`. [Manage Audience Columns](/docs/mcp/tools/manage-audience-columns) and [Manage Audience Rows](/docs/mcp/tools/manage-audience-rows) take it as `audienceId` on every call, so no other write can happen until this tool runs. Then fill it, two ways: **From ZoomInfo search** Call [Search Companies](/docs/mcp/tools/search-companies) or [Search Contacts](/docs/mcp/tools/search-contacts) first, then pass those exact parameters as `searchQuery`. A job pulls every matching record into the audience with no row limit. > **Pass searchQuery or get an empty audience** > > If a search ran to fulfill the request, its parameters must go into `searchQuery`. Omitting it creates an empty audience with no error, the most common failure on this tool. **From your own data** Create the audience without `searchQuery`, then load records with [Manage Audience Rows](/docs/mcp/tools/manage-audience-rows), up to 50 per call. ## Technical Details ### Credits Creating or updating the audience record itself is free. Ingesting records is not. Every ingest path costs data credits and checks Records Under Management first, so a record your organization already enriched in the past 12 months costs nothing to bring in again. | Ingest path | Charge | | --- | --- | | ZoomInfo search | 1 data credit per record ingested, subject to Records Under Management. Ingesting 4,000 companies costs up to 4,000 credits. | | Your own records | Data credits on matched rows only, subject to Records Under Management. Rows that don't match a ZoomInfo record ingest free. | Unmatched rows are fully usable, and AI enrichment columns run against them, subject to the per-capability requirements on [Manage Audience Columns](/docs/mcp/tools/manage-audience-columns). See [Credits & Billing](/docs/mcp/credits). ### Requirements A ZoomInfo account with data credits. Free signup accounts include 1,000. On a subscription, MCP draws from bulk data credits rather than recurring monthly credits; see [Which Credits MCP Uses](/docs/mcp/credits#which-credits-mcp-uses). `agentInstruction` is required on both create and update. A downstream agent reads that field and executes it without access to your conversation, so it has to carry the full request on its own. A workable value looks like this: ```text Create a COMPANY audience named "Boston Software 100-500" from the attached search: software companies in the Boston metro with 100 to 500 employees. Description: Q4 outbound targets for the New England team. ``` If the instruction text conflicts with a structured field like `name` or `type`, the structured field wins. ### Limits An audience supports up to 40 million cells. That is a few hundred columns across hundreds of thousands of rows, or a handful of columns across millions of rows; the ceiling is the product of the two, not either one alone. In practice your working limit is usually your data credit balance, or the allocation your admin sets on a ZoomInfo subscription. ### Immutable fields `type` and `searchQuery` cannot be changed after creation. Both are silently ignored if passed on update, never rejected with an error. To change either, create a new audience. ### The searchQuery rule If [Search Companies](/docs/mcp/tools/search-companies) or [Search Contacts](/docs/mcp/tools/search-contacts) was called to fulfill the request, its exact parameters must be passed through as `searchQuery`. The rule carries across conversation turns. A follow-up like "create an audience for that" inherits the earlier search's parameters, and if the criteria were refined across several calls, only the final confirmed version belongs in `searchQuery`. ### Automatic Tool Selection The AI reaches for Upsert Audience when you describe a set of records you want to work with as a group: "build me a list of", "create an audience for", "save these as". When it's genuinely unclear whether you mean a new audience or an update, or whether records should come from ZoomInfo prospecting or your own data, it should ask rather than guess. ## Example Prompts > *"Find software companies in Boston with 100 to 500 employees and save them as an audience."* > *"Create an empty company audience called Q3 Win-Back so I can load our CRM export into it."* > *"Rename my Boston Tech audience to FY26 Expansion Targets and move it to the Marketing folder."* > *"Add a note to the win-back audience saying marketing signed off on the definition."* Once the audience exists, add research columns with [Manage Audience Columns](/docs/mcp/tools/manage-audience-columns).