MMetadata /docs
Docs/Tools/update_target_group

update_target_group

Update existing target group with new name and/or targeting criteria.

Destructive audiences

Deletes, archives, launches or moves budget. Do not give an agent this one without a human gate.

What it does

Update existing target group with new name and/or targeting criteria. Supports BOTH include AND exclude rules — including adding/removing exclude audiences.

**CRITICAL - PUT REQUEST**: You MUST provide ALL fields, not just changed ones.
- 'name' is ALWAYS REQUIRED even if not changing
- If updating targeting, provide complete targeting object (full include + exclude)
- Always retrieve current config first via retrieve_target_group_by_id and merge changes onto it

PREREQUISITE WORKFLOW:
1. list_target_groups(name="X") → get ID
2. retrieve_target_group_by_id(target_group_id=ID) → get current config, check isModifiable fields, copy existing exclude audiences
3. search_target_group_criteria → get new criteria IDs
4. estimate_target_group → MANDATORY: verify isMatchCountTooSmall=false
5. update_target_group with ID and ALL required fields (full targeting object)

MODIFIABILITY: Name always modifiable. LOCATION usually isModifiable=false. Check retrieve_target_group_by_id response for other fields.

TARGETING STRUCTURE: Same as create_target_group — full include array + single exclude object containing both `criteria` and `audiences`. See create_target_group description for the full example payload (with NATIVE_LOCATION, AGE, COMPANY_NAME exclude criteria, and FIRMOGRAPHIC_EXCLUDE audience). Only update criteria with isModifiable=true.

⚠️ AUDIENCES ≠ TARGET GROUPS. Both `include[].audiences` and `exclude.audiences` accept Custom Audience records ONLY (the entities returned by `get_matched_audiences`). Target Groups (the entities returned by `list_target_groups` / `retrieve_target_group_by_id`) are a separate entity in a separate ID space and CANNOT be attached here; the platform silently drops or rejects them. If the user names "X" and only `list_target_groups` matches it (not `get_matched_audiences`), do NOT pass the Target Group's id as `mdAudienceId`. Stop, tell the user "X is a Target Group, not a Custom Audience", and offer to rebuild X as a Custom Audience (e.g. via `create_audiences` with the same criteria) before retrying.

ADDING/REMOVING EXCLUDE AUDIENCES: Provide the COMPLETE desired `exclude.audiences` array. Each entry needs: `mdAudienceId` (integer, REQUIRED — the numeric Custom Audience id like 49067 from `get_matched_audiences`, NEVER the audience name string, NEVER a placeholder like 1/2/3/4 (rejected pre-flight), and NEVER a Target Group id from `list_target_groups`; see the AUDIENCES ≠ TARGET GROUPS note above), `name`, `type` (EXCLUDE variant like FIRMOGRAPHIC_EXCLUDE/RETARGETING_EXCLUDE/CONTACT_LIST_EXCLUDE), `matchCount`, `matchCountType`, `inactive`, and the audience's own `criteria` array. To remove an exclusion, omit it from the array. To add one, append it.

RESPONSE: {id, name, channel, audienceSize, status, modifiedDate, targeting}

VALIDATION: Must estimate first and verify isMatchCountTooSmall=false before updating.

Arguments

ArgumentTypeNotes
target_group_id integer required The unique ID of the target group to update. Must be a positive integer. Use list_target_groups to find the ID by name.
name string required REQUIRED: Target group name. CRITICAL - This is a PUT request so you MUST provide the name even if not changing it. Use retrieve_target_group_by_id to get the current name if you don't have it.
targeting object Updated targeting configuration (optional). Structure must match create_target_group format. Only update criteria that have isModifiable=true in the current configuration. All criteria IDs/references must come from search_target_group_criteria tool. REQUIRED: Must estimate this targeting first and v

Request

curl
curl -s -X POST https://mcp-server.metadata.io/mcp \
  -H "Authorization: $METADATA_PAT" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"update_target_group","arguments":{"target_group_id":0,"name":"<name>"}}}'

Response

No recorded response. This tool can delete, archive, launch or move budget, so it is never executed to build these docs. The request above is still the exact shape to send. Nothing on this page is invented.

Other audiences tools:

All 160 tools · machine-readable index