---
title: "All 160 MCP tools. Metadata Developer Docs"
url: https://metadata.io/developers/tools/
description: "Every tool the Metadata MCP server exposes, generated from its own tools/list response: 65 read-only, 56 that write and 39 marked destructive, each with its full JSON Schema."
source: metadata.io
---

# All 160 MCP tools

Generated from the server's own `tools/list` response on 2026-09-05. If the server gains a tool, this page has it on the next build. Nothing here is maintained by hand.

160 shown

## Audiences and targeting 39

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `custom_audience_id` | integer |   | The numeric ID of the custom audience to archive. |
| `audience_name` | string |   | The name of the custom audience to archive. If provided without custom_audience_id, the tool will search for the audience by name to resolve the ID. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/archive_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `segment_id` | integer | required | The ID of the segment from list_segments tool. Use list_segments to find available segment IDs. |
| `name` | string | required | Name for the new audience. Must be unique and descriptive. Example: 'High Intent Accounts - 30 Days' |
| `lookback_window` | integer | required | Number of days to look back in the segment results. Range: 1 to 365 days. Example: 30 for last 30 days, 90 for last quarter, 365 for last year. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_audience_from_segment) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience name (required) |
| `topics` | array | required | Array of buyer intent topics (required). Use get_intent_topics to retrieve available topics. Example: ['Pardot', 'Salesforce'] |
| `industries` | array |   | Industry IDs for company targeting (optional). Valid range: 1-148. Example: [4, 96] |
| `employees` | array |   | Employee count ranges for company targeting (optional). Valid values: 'FROM_1_TO_10', 'FROM_10_TO_50', 'FROM_50_TO_200', 'FROM_200_TO_500', 'FROM_500_TO_1000', 'FROM_1000_TO_5000', 'FROM_5000_TO_10000', 'OVER_10000' |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `location_state_ids` | array |   | State IDs for geographic targeting (optional). Valid US State IDs: 1 (Alabama), 2 (Alaska), 3 (Arizona), 4 (Arkansas), 5 (California), 6 (Colorado), 7 (Connecticut), 8 (Delaware), 9 (Florida), 10 (Georgia), 11 (Hawaii), 12 (Idaho), 13 (Illinois), 14 (Indiana), 15 (Iowa), 16 (Kansas), 17 (Kentucky), |
| `job_title_includes` | array |   | Free text keywords for job titles to include (optional). Example: ['Software Engineer', 'Manager'] |
| `job_title_excludes` | array |   | Free text keywords for job titles to exclude (optional). Example: ['Senior', 'Lead'] |
| `job_function_include_ids` | array |   | Job function IDs to include (optional). Valid IDs: 1 (Marketing), 2 (Sales), 3 (Customer Service), 4 (Finance), 5 (HR), 6 (PR), 7 (Media), 8 (Design), 9 (Engineering), 10 (Operations), 11 (Legal), 12 (Education), 13 (Health), 14 (Real Estate), 15 (Accounting), 16 (Administrative), 17 (Business Devel |
| `job_function_exclude_ids` | array |   | Job function IDs to exclude (optional). Valid IDs: 1-28 as listed above |
| `seniority_include_ids` | array |   | Seniority level IDs to include (optional). Valid IDs: 2 (Manager), 3 (Director), 4 (VP), 5 (CXO), 6 (Unpaid), 7 (Training), 8 (Senior), 9 (Owner), 10 (Entry), 11 (Partner). Example: [10, 7] for Entry and Training |
| `seniority_exclude_ids` | array |   | Seniority level IDs to exclude (optional). Valid IDs: 2-11 as listed above |
| `contacts_per_company_limit` | integer |   | Maximum number of contacts to target per company (optional). Example: 20 |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_bombora_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `audience_name` | string | required | Name for the new audience (required). |
| `companies` | object |   | Inline map of company names to website URLs (optional). MUTUALLY EXCLUSIVE with `companies_source_csv_url`. Example: {"Acme Corp": "https://acme.com"} |
| `companies_source_csv_url` | string |   | Public URL of a CSV with header EXACTLY `companyname,companywebsite` (case-insensitive). Use when the user attached a CSV to the chat — the URL comes via `AudienceBrief.attached_file_urls`. MUTUALLY EXCLUSIVE with `companies`. |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `employees` | array |   | LinkedIn employee count ranges for audience targeting. Valid values: 1, 2-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, +10001. Example: ['201-500', '501-1000'] |
| `revenues` | array |   | LinkedIn revenue ranges for audience targeting. Valid values: Under $1M, $1M-$10M, $10M-$100M, $100M-$1B, $1B+. Example: ['$1M-$10M', '$10M-$100M'] |
| `company_names` | array |   | Free-text company names (resolved to LinkedIn company IDs). Example: ['Metadata', 'Google'] |
| `job_titles` | array |   | Free-text job titles (resolved to LinkedIn job-title IDs). Example: ['Software Engineer', 'Product Manager'] |
| `skills` | array |   | Free-text professional skills (resolved to LinkedIn skill IDs). Example: ['HubSpot', 'Salesforce'] |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_csv_upload_linkedin_native_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience name (required). |
| `industries` | array |   | Facebook native industry categories for audience targeting. Valid values: Administrative Services, Architecture and Engineering, Arts, Entertainment, Sports and Media, Business and Finance, Business decision maker titles and interests, Cleaning and Maintenance Services, Community and Social Services |
| `countries` | array |   | List of country names to target. Each must be a valid country name (e.g., ['United States', 'Brazil']). Resolved to platform country IDs before submission. |
| `job_titles` | array |   | Free-text job title strings for targeting. Example: ['Software Engineer', 'Senior Developer', 'Product Owner'] |
| `interests` | array |   | Free-text interest strings for targeting. Example: ['Java', 'Python', 'Cloud Computing', 'Machine Learning'] |
| `min_age` | integer | required | Minimum age for audience targeting. Must be between 21 and 65, and less than or equal to max_age. |
| `max_age` | integer | required | Maximum age for audience targeting. Must be between 21 and 65, and greater than or equal to min_age. |
| `estimate_only` | boolean |   | If true, do NOT create the audience — only estimate its size and return the expected contact count. Use this when the user wants to preview Facebook audience size before committing. Defaults to false (audience is created). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_facebook_native_criteria_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience name (required) |
| `industries` | array |   | Industry IDs for firmographic/technographic filtering (optional). Valid IDs: 1=Defense & Space, 3=Computer Hardware, 4=Computer Software, 5=Computer Networking, 6=Internet, 7=Semiconductors, 8=Telecommunications, 9=Law Practice, 10=Legal Services, 11=Management Consulting, 12=Biotechnology, 13=Medic |
| `employees` | array |   | Employee count ranges. Valid enum values: LESS_THAN_10 (0-9), FROM_10_TO_50 (10-49), FROM_50_TO_200 (50-199), FROM_200_TO_500 (200-499), FROM_500_TO_1000 (500-999), FROM_1000_TO_5000 (1,000-4,999), FROM_5000_TO_10000 (5,000-9,999), OVER_10000 (10,000+) |
| `revenue` | array |   | Revenue ranges. Valid enum values: LESS_THAN_1M ($0-$1M), FROM_1M_TO_10M ($1M-$10M), FROM_10M_TO_50M ($10M-$50M), FROM_50M_TO_100M ($50M-$100M), FROM_100M_TO_200M ($100M-$200M), FROM_200M_TO_500M ($200M-$500M), FROM_500M_TO_1000M ($500M-$1B), OVER_1000M ($1B+) |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `location_state_ids` | array |   | State IDs for geographic targeting (optional). Valid US State IDs: 1 (Alabama), 2 (Alaska), 3 (Arizona), 4 (Arkansas), 5 (California), 6 (Colorado), 7 (Connecticut), 8 (Delaware), 9 (Florida), 10 (Georgia), 11 (Hawaii), 12 (Idaho), 13 (Illinois), 14 (Indiana), 15 (Iowa), 16 (Kansas), 17 (Kentucky), |
| `job_title_includes` | array |   | Free text keywords for job titles to include (optional). Example: ['Software Engineer', 'Manager'] |
| `job_title_excludes` | array |   | Free text keywords for job titles to exclude (optional). Example: ['Senior', 'Lead'] |
| `job_function_include_ids` | array |   | Job function IDs to include (optional). Valid IDs: 1 (Marketing), 2 (Sales), 3 (Customer Service), 4 (Finance), 5 (HR), 6 (PR), 7 (Media), 8 (Design), 9 (Engineering), 10 (Operations), 11 (Legal), 12 (Education), 13 (Health), 14 (Real Estate), 15 (Accounting), 16 (Administrative), 17 (Business Devel |
| `job_function_exclude_ids` | array |   | Job function IDs to exclude (optional). Valid IDs: 1-28 as listed above |
| `seniority_include_ids` | array |   | Seniority level IDs to include (optional). Valid IDs: 2 (Manager), 3 (Director), 4 (VP), 5 (CXO), 6 (Unpaid), 7 (Training), 8 (Senior), 9 (Owner), 10 (Entry), 11 (Partner). Example: [10, 7] for Entry and Training |
| `seniority_exclude_ids` | array |   | Seniority level IDs to exclude (optional). Valid IDs: 2-11 as listed above |
| `contacts_per_company_limit` | integer |   | Maximum number of contacts to target per company (optional). Example: 20 |
| `estimate_only` | boolean |   | If true, do NOT create the audience — only estimate its size and return the counts. Use this when the user wants to preview how many companies/contacts match the criteria before committing. Defaults to false (audience is created). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_firmographic_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience name (required, max 50 characters). |
| `intent_days` | integer | required | Days to look back for G2 intent signals (required, 1-365). |
| `buying_stages` | array |   | Buying stages to target. The platform REQUIRES at least one; if the user did not specify, ASK them before calling — do NOT default. |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `location_state_ids` | array |   | State IDs for geographic targeting (optional). Valid US State IDs: 1 (Alabama), 2 (Alaska), 3 (Arizona), 4 (Arkansas), 5 (California), 6 (Colorado), 7 (Connecticut), 8 (Delaware), 9 (Florida), 10 (Georgia), 11 (Hawaii), 12 (Idaho), 13 (Illinois), 14 (Indiana), 15 (Iowa), 16 (Kansas), 17 (Kentucky), |
| `job_title_includes` | array |   | Free text keywords for job titles to include (optional). Example: ['Software Engineer', 'Manager'] |
| `job_title_excludes` | array |   | Free text keywords for job titles to exclude (optional). Example: ['Senior', 'Lead'] |
| `job_function_include_ids` | array |   | Job function IDs to include (optional). Valid IDs: 1 (Marketing), 2 (Sales), 3 (Customer Service), 4 (Finance), 5 (HR), 6 (PR), 7 (Media), 8 (Design), 9 (Engineering), 10 (Operations), 11 (Legal), 12 (Education), 13 (Health), 14 (Real Estate), 15 (Accounting), 16 (Administrative), 17 (Business Devel |
| `job_function_exclude_ids` | array |   | Job function IDs to exclude (optional). Valid IDs: 1-28 as listed above |
| `seniority_include_ids` | array |   | Seniority level IDs to include (optional). Valid IDs: 2 (Manager), 3 (Director), 4 (VP), 5 (CXO), 6 (Unpaid), 7 (Training), 8 (Senior), 9 (Owner), 10 (Entry), 11 (Partner). Example: [10, 7] for Entry and Training |
| `seniority_exclude_ids` | array |   | Seniority level IDs to exclude (optional). Valid IDs: 2-11 as listed above |
| `contacts_per_company_limit` | integer |   | Maximum number of contacts to target per company (optional). Example: 20 |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_g2_intent_dynamic_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience name (required, max 50 characters). |
| `intent_days` | integer | required | Days to look back for G2 intent signals (required, 1-365). |
| `buying_stages` | array |   | Buying stages to target. The platform REQUIRES at least one; if the user did not specify, ASK them before calling — do NOT default. |
| `employees` | array |   | LinkedIn employee count ranges for audience targeting. Valid values: 1, 2-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, +10001. Example: ['201-500', '501-1000'] |
| `revenues` | array |   | LinkedIn revenue ranges for audience targeting. Valid values: Under $1M, $1M-$10M, $10M-$100M, $100M-$1B, $1B+. Example: ['$1M-$10M', '$10M-$100M'] |
| `company_names` | array |   | Free-text company names to target (resolved server-side to LinkedIn company IDs). Example: ['Metadata', 'Google', 'Salesforce'] |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `job_titles` | array |   | Free-text job titles (resolved to LinkedIn job-title IDs). Example: ['Software Engineer', 'Product Manager'] |
| `skills` | array |   | Free-text professional skills (resolved to LinkedIn skill IDs). Example: ['HubSpot', 'Salesforce', 'Python'] |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_g2_intent_linkedin_native_dynamic_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience name (required, max 50 characters). |
| `intent_days` | integer | required | Days to look back for G2 intent signals (required, 1-365). |
| `buying_stages` | array |   | Buying stages to target. The platform REQUIRES at least one; if the user did not specify, ASK them before calling — do NOT default. |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `location_state_ids` | array |   | State IDs for geographic targeting (optional). Valid US State IDs: 1 (Alabama), 2 (Alaska), 3 (Arizona), 4 (Arkansas), 5 (California), 6 (Colorado), 7 (Connecticut), 8 (Delaware), 9 (Florida), 10 (Georgia), 11 (Hawaii), 12 (Idaho), 13 (Illinois), 14 (Indiana), 15 (Iowa), 16 (Kansas), 17 (Kentucky), |
| `job_title_includes` | array |   | Free text keywords for job titles to include (optional). Example: ['Software Engineer', 'Manager'] |
| `job_title_excludes` | array |   | Free text keywords for job titles to exclude (optional). Example: ['Senior', 'Lead'] |
| `job_function_include_ids` | array |   | Job function IDs to include (optional). Valid IDs: 1 (Marketing), 2 (Sales), 3 (Customer Service), 4 (Finance), 5 (HR), 6 (PR), 7 (Media), 8 (Design), 9 (Engineering), 10 (Operations), 11 (Legal), 12 (Education), 13 (Health), 14 (Real Estate), 15 (Accounting), 16 (Administrative), 17 (Business Devel |
| `job_function_exclude_ids` | array |   | Job function IDs to exclude (optional). Valid IDs: 1-28 as listed above |
| `seniority_include_ids` | array |   | Seniority level IDs to include (optional). Valid IDs: 2 (Manager), 3 (Director), 4 (VP), 5 (CXO), 6 (Unpaid), 7 (Training), 8 (Senior), 9 (Owner), 10 (Entry), 11 (Partner). Example: [10, 7] for Entry and Training |
| `seniority_exclude_ids` | array |   | Seniority level IDs to exclude (optional). Valid IDs: 2-11 as listed above |
| `contacts_per_company_limit` | integer |   | Maximum number of contacts to target per company (optional). Example: 20 |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_g2_intent_static_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience name (required, must be shorter than 50 characters). |
| `job_titles` | array |   | Free-text job title strings for targeting. Example: ['Software Engineer', 'Product Manager'] |
| `skills` | array |   | Free-text skill strings for targeting. Example: ['HubSpot', 'Salesforce', 'Python'] |
| `company_names` | array |   | Free-text company name strings for targeting. Example: ['Metadata', 'Google', 'Salesforce'] |
| `employees` | array |   | LinkedIn employee count ranges for audience targeting. Valid values: 1, 2-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, +10001. Example: ['201-500', '501-1000'] |
| `revenues` | array |   | LinkedIn revenue ranges for audience targeting. Valid values: Under $1M, $1M-$10M, $10M-$100M, $100M-$1B, $1B+. Example: ['$1M-$10M', '$10M-$100M'] |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `estimate_only` | boolean |   | If true, do NOT create the audience — only estimate its size and return the expected contact count. Use this when the user wants to preview LinkedIn audience size before committing. Defaults to false (audience is created). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_linkedin_native_criteria_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `custom_audience_name` | string | required | Audience display name. Must not contain '/'. |
| `library_list_id` | integer | required | The library list id from list_marketing_automation_lists. |
| `provider` | string | required | The Marketing-Automation provider that owns the list.one of: `HUBSPOT`, `MARKETO` |
| `variant` | string | required | STATIC = snapshot (MA_CONTACTS_STATIC); DYNAMIC = refreshing (MA_CONTACTS_DYNAMIC). Ask the user if unspecified.one of: `STATIC`, `DYNAMIC` |
| `list_name` | string |   | Optional: the source list's own name, from list_marketing_automation_lists. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_marketing_automation_contacts_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | The name for the new Reddit target group. Must be unique, descriptive, and UNDER 50 characters — the platform rejects 50+ character names with a 400. |
| `targeting` | object | required | Complete Reddit targeting configuration with include/exclude rules. LOCATION must be the first include block. All references must come from search_reddit_criteria. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_reddit_target_group) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `audience_data` | object | required | Complete audience object from get_retargeting_audiences response. Should contain: id, name, type, subtype, channel, matchCount, externalAccountId, and other relevant fields. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_retargeting_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience display name. |
| `criteria_id` | integer | required | The Salesforce mixed-criteria id from list_salesforce_mixed_criteria. |
| `variant` | string | required | STATIC = snapshot (SFDC_CONTACTS_STATIC); DYNAMIC = refreshing (SFDC_CONTACTS_DYNAMIC). Ask the user if unspecified.one of: `STATIC`, `DYNAMIC` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_salesforce_contacts_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Descriptive, unique segment name. |
| `criteria` | object | required | Criteria object with operator and match fields. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_segment) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | The name for the new target group. Must be unique, descriptive, and UNDER 50 characters — the platform rejects 50+ character names with a 400. |
| `channel` | string | required | The advertising channel for the target group. Only LINKEDIN is currently supported.one of: `LINKEDIN` |
| `targeting` | object |   | Complete targeting configuration with include/exclude rules... |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_target_group) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Audience name (required). Maximum 50 characters. |
| `technologies` | array | required | Array of technology names to target (required). Example: ['Salesforce', 'HubSpot', 'Marketo'] |
| `industries` | array |   | Industry IDs for firmographic/technographic filtering (optional). Valid IDs: 1=Defense & Space, 3=Computer Hardware, 4=Computer Software, 5=Computer Networking, 6=Internet, 7=Semiconductors, 8=Telecommunications, 9=Law Practice, 10=Legal Services, 11=Management Consulting, 12=Biotechnology, 13=Medic |
| `employees` | array |   | Employee count ranges for firmographic filtering (optional). Valid enum values: LESS_THAN_10 (0-9), FROM_10_TO_50 (10-49), FROM_50_TO_200 (50-199), FROM_200_TO_500 (200-499), FROM_500_TO_1000 (500-999), FROM_1000_TO_5000 (1,000-4,999), FROM_5000_TO_10000 (5,000-9,999), OVER_10000 (10,000+). Example: |
| `revenue` | array |   | Revenue ranges for firmographic filtering (optional). Valid enum values: LESS_THAN_1M ($0-$1M), FROM_1M_TO_10M ($1M-$10M), FROM_10M_TO_50M ($10M-$50M), FROM_50M_TO_100M ($50M-$100M), FROM_100M_TO_200M ($100M-$200M), FROM_200M_TO_500M ($200M-$500M), FROM_500M_TO_1000M ($500M-$1B), OVER_1000M ($1B+). |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `location_state_ids` | array |   | State IDs for geographic targeting (optional). Valid US State IDs: 1 (Alabama), 2 (Alaska), 3 (Arizona), 4 (Arkansas), 5 (California), 6 (Colorado), 7 (Connecticut), 8 (Delaware), 9 (Florida), 10 (Georgia), 11 (Hawaii), 12 (Idaho), 13 (Illinois), 14 (Indiana), 15 (Iowa), 16 (Kansas), 17 (Kentucky), |
| `job_title_includes` | array |   | Free text keywords for job titles to include (optional). Example: ['Software Engineer', 'Manager'] |
| `job_title_excludes` | array |   | Free text keywords for job titles to exclude (optional). Example: ['Senior', 'Lead'] |
| `job_function_include_ids` | array |   | Job function IDs to include (optional). Valid IDs: 1 (Marketing), 2 (Sales), 3 (Customer Service), 4 (Finance), 5 (HR), 6 (PR), 7 (Media), 8 (Design), 9 (Engineering), 10 (Operations), 11 (Legal), 12 (Education), 13 (Health), 14 (Real Estate), 15 (Accounting), 16 (Administrative), 17 (Business Devel |
| `job_function_exclude_ids` | array |   | Job function IDs to exclude (optional). Valid IDs: 1-28 as listed above |
| `seniority_include_ids` | array |   | Seniority level IDs to include (optional). Valid IDs: 2 (Manager), 3 (Director), 4 (VP), 5 (CXO), 6 (Unpaid), 7 (Training), 8 (Senior), 9 (Owner), 10 (Entry), 11 (Partner). Example: [10, 7] for Entry and Training |
| `seniority_exclude_ids` | array |   | Seniority level IDs to exclude (optional). Valid IDs: 2-11 as listed above |
| `contacts_per_company_limit` | integer |   | Maximum number of contacts to target per company (optional). Example: 20 |
| `estimate_only` | boolean |   | If true, do NOT create the audience — only estimate its size and return the counts. Use this when the user wants to preview how many companies/contacts match the criteria before committing. Defaults to false (audience is created). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_technographic_audience) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `channel` | string | required | Channel to estimate for. LINKEDIN (default) takes criteria ids from search_target_group_criteria; REDDIT takes them from search_reddit_criteria and is estimated the same way (PRD-31759). Omit for LinkedIn.one of: `LINKEDIN`, `REDDIT` |
| `targeting` | object |   | Complete targeting configuration with include/exclude rules. Structure: { "include": [ { "criteria": [{"type": str, "data": object}], "audiences": [] } ], "exclude": {"criteria": [], "audiences": []} } All criteria IDs/references must come from search_target_group_criteria tool. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/estimate_target_group) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domains` | array | required | Seed company domains, e.g. ['metadata.io']. |
| `limit` | integer |   | Max lookalikes to return (default 10). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/find_lookalike_companies) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `filename` | string |   | Filter by account list filename (supports partial matching) |
| `page` | integer |   | Page number for pagination (0-based) |
| `size` | integer |   | Number of results per page |
| `sort` | string |   | Sort criteria (e.g., 'createdDate,desc', 'name,asc', 'accountsCount,desc') |
| `status` | string |   | Filter by status (e.g., READY, PROCESSING, ERROR) |
| `type` | string |   | Filter by list type (e.g., CSV, WEBSITE_RETARGETING) |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_abm_account_lists) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `page` | integer |   | Page number for pagination (0-based) |
| `size` | integer |   | Number of results per page |
| `sort` | string |   | Sort criteria (e.g., 'creationDate,desc', 'name,asc', 'audienceSize,desc') |
| `name` | string | required | Filter by audience name (supports partial matching) |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_audience_details) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `audience_ids` | array | required | Array of audience IDs to retrieve detailed information for. Example: [42828, 42829, 42831] |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_deep_audience_details) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

Takes no arguments.

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_intent_topics) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `type` | array | required | Array of audience targeting types to filter by. If omitted, searches all targeting types. |
| `channel` | string |   | The advertising channel to filter campaigns byone of: `LINKEDIN`, `FACEBOOK`, `GOOGLE_ADS`, `INSTAGRAM`, `TWITTER`, `YOUTUBE`, `REDDIT`, `MICROSOFT_ADS` |
| `page` | integer |   | Page number for pagination (0-indexed) |
| `sort` | string |   | Sort field and direction in format 'field,direction'. Common fields: createdDate. Direction: asc or desc. |
| `size` | integer |   | Number of results per page |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_matched_audiences) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `channel` | string | required | The advertising channel to fetch retargeting audiences forone of: `GOOGLE_ADS`, `LINKEDIN`, `FACEBOOK` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_retargeting_audiences) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `segment_id` | integer |   | Segment ID (fastest lookup). |
| `segment_name` | string |   | Segment name (fuzzy matching, case-insensitive). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_segment_criteria) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `provider` | string | required | The Marketing-Automation provider to list lists for.one of: `HUBSPOT`, `MARKETO` |
| `list_type` | string |   | Optional list-type filter. If omitted, the provider's own list types are queried and merged (HubSpot: STATIC_LIST + ACTIVE_LIST; Marketo: all three).one of: `SMART_LIST`, `STATIC_LIST`, `ACTIVE_LIST` |
| `name` | string |   | Optional list-name filter (partial match). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_marketing_automation_lists) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `qualified` | boolean |   | When true, keep only criteria whose generated filter matches qualified-signal fields. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_salesforce_mixed_criteria) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string |   | Optional fuzzy search by name. |
| `sort` | string |   | Sort format: field,direction. Default: name,asc |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_segments) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string |   | Optional name filter for searching target groups (partial matching, case-insensitive). Example: 'engineer' matches 'Engineers EMEA', 'Senior Engineers', etc. |
| `sort` | string |   | Sort criteria. Options: 'createdDate,desc' (newest first), 'createdDate,asc' (oldest first), 'name,asc' (A-Z), 'name,desc' (Z-A). Default: 'createdDate,desc' |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_target_groups) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the campaign |
| `channel_audiences` | object | required | Map of channel type to list of audience names to remove. Example: {"FACEBOOK": ["Audience A"], "LINKEDIN": ["Audience B"]} |

[Full page, schema and recorded response](https://metadata.io/developers/tools/remove_audiences_from_campaign) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the campaign |
| `channel_target_groups` | object | required | Map of channel type to list of targeting group names to remove. Example: {"LINKEDIN": ["Tech Decision Makers"]} |

[Full page, schema and recorded response](https://metadata.io/developers/tools/remove_target_groups_from_campaign) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `target_group_id` | integer | required | The unique ID of the target group to retrieve. Must be a positive integer. If you don't have the ID, use list_target_groups to search by name first. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/retrieve_target_group_by_id) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `criteria_type` | string | required | Type of Reddit criteria to search. communities/interests/keywords require search_terms; locations returns countries/states (search_terms optional).one of: `communities`, `interests`, `keywords`, `locations` |
| `search_terms` | array |   | Search keywords (min 2 characters). Required for communities/interests/keywords. Example: ['technology'] |

[Full page, schema and recorded response](https://metadata.io/developers/tools/search_reddit_criteria) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `channel` | string | required | The advertising channel for which to retrieve criteria. Only LINKEDIN is supported.one of: `LINKEDIN` |
| `criteria_type` | string |   | Type of targeting criteria to retrieve or search. List-based (returns predefined options): - age-ranges: Age range segments - company-categories: Company type classifications - company-growth-rates: Company growth classifications - revenues: Company revenue ranges - employees: Employee count ranges one of: `age-ranges`, `company-categories`, `company-growth-rates`, `revenues`, `employees`, `industry-taxonomy`, `jobFunctions`, `seniority`, `followed-companies`, `locations`, `job-title`, `member-groups` |
| `search_terms` | array |   | Array of search keywords for search-based criteria (job-title, member-groups, interests, traits). Example: ['engineer', 'developer'] |
| `reference_type` | string |   | Specific reference type for search operations (LinkedIn only). Auto-determined from criteria_type and channel if not provided.one of: `LINKEDIN_JOB_TITLES`, `LINKEDIN_MEMBER_GROUPS`, `BUYER_INTENT_INDUSTRIES` |
| `exact_match` | boolean |   | Whether to require exact matches in search (default: true). Set to false for broader/fuzzy matching. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/search_target_group_criteria) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `custom_audience_id` | integer |   | The numeric ID of the custom audience to unarchive. |
| `audience_name` | string |   | The name of the custom audience to unarchive. If provided without custom_audience_id, the tool will search for the audience by name to resolve the ID. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/unarchive_audience) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `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 |

[Full page, schema and recorded response](https://metadata.io/developers/tools/update_target_group) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `audience_name` | string | required | Name for the new audience (required). |
| `companies` | object |   | Inline map of company names to website URLs (optional). Example: {"Acme Corp": "https://acme.com", "Globex": "https://globex.com"}. MUTUALLY EXCLUSIVE with `companies_source_csv_url` — provide exactly one. |
| `companies_source_csv_url` | string |   | Public URL of a CSV file with header EXACTLY `companyname,companywebsite` (case-insensitive). The MCP server downloads, validates, and parses the file. Use this when the user attached a CSV to the chat — the URL is surfaced via `AudienceBrief.attached_file_urls`. MUTUALLY EXCLUSIVE with `companies`. |
| `location_country_ids` | array |   | Country IDs for geographic targeting (optional). Valid IDs: 1 (Afghanistan), 2 (Albania), 3 (Algeria), 4 (American Samoa), 5 (Andorra), 6 (Angola), 7 (Anguilla), 8 (Antarctica), 9 (Antigua and Barbuda), 10 (Argentina), 11 (Armenia), 12 (Aruba), 13 (Australia), 14 (Austria), 15 (Azerbaijan), 16 (Baha |
| `location_state_ids` | array |   | State IDs for geographic targeting (optional). Valid US State IDs: 1 (Alabama), 2 (Alaska), 3 (Arizona), 4 (Arkansas), 5 (California), 6 (Colorado), 7 (Connecticut), 8 (Delaware), 9 (Florida), 10 (Georgia), 11 (Hawaii), 12 (Idaho), 13 (Illinois), 14 (Indiana), 15 (Iowa), 16 (Kansas), 17 (Kentucky), |
| `job_title_includes` | array |   | Free text keywords for job titles to include (optional). Example: ['Software Engineer', 'Manager'] |
| `job_title_excludes` | array |   | Free text keywords for job titles to exclude (optional). Example: ['Senior', 'Lead'] |
| `job_function_include_ids` | array |   | Job function IDs to include (optional). Valid IDs: 1 (Marketing), 2 (Sales), 3 (Customer Service), 4 (Finance), 5 (HR), 6 (PR), 7 (Media), 8 (Design), 9 (Engineering), 10 (Operations), 11 (Legal), 12 (Education), 13 (Health), 14 (Real Estate), 15 (Accounting), 16 (Administrative), 17 (Business Devel |
| `job_function_exclude_ids` | array |   | Job function IDs to exclude (optional). Valid IDs: 1-28 as listed above |
| `seniority_include_ids` | array |   | Seniority level IDs to include (optional). Valid IDs: 2 (Manager), 3 (Director), 4 (VP), 5 (CXO), 6 (Unpaid), 7 (Training), 8 (Senior), 9 (Owner), 10 (Entry), 11 (Partner). Example: [10, 7] for Entry and Training |
| `seniority_exclude_ids` | array |   | Seniority level IDs to exclude (optional). Valid IDs: 2-11 as listed above |
| `contacts_per_company_limit` | integer |   | Maximum number of contacts to target per company (optional). Example: 20 |

[Full page, schema and recorded response](https://metadata.io/developers/tools/upload_account_list_csv_audience) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `audience_name` | string | required | Name for the new contact list audience (required). |
| `contacts` | array |   | Inline array of contact objects (optional). Each object represents one person/contact with fields: email (required), firstname, lastname, jobtitle, employeecompany, country, appleidfa, googleaid. Minimum 300 contacts, maximum 300,000 contacts. MUTUALLY EXCLUSIVE with `contacts_source_csv_url` — prov |
| `contacts_source_csv_url` | string |   | Public URL of a contacts CSV file with header EXACTLY `email,firstname,lastname,jobtitle,employeecompany,country,appleidfa,googleaid` (case-insensitive). The MCP server downloads, validates, and uploads the file. Use this when the user attached a CSV to the chat — the URL is surfaced via `AudienceBr |

[Full page, schema and recorded response](https://metadata.io/developers/tools/upload_contact_list_csv_audience) · [machine index](https://metadata.io/developers/tools.json)

## Campaigns and budgets 27

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_data` | object | required | Campaign data with fields to edit and/or elements to add |

[Full page, schema and recorded response](https://metadata.io/developers/tools/add_and_edit_campaign_elements) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_data` | object | required | Native (N×N×N) campaign edit payload: campaignId + optional campaign-level fields + per-channel `containers[]` (append) and optional `target_groups[]`. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/add_and_edit_native_campaign_elements) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The wizard campaign ID to check launch readiness for |

[Full page, schema and recorded response](https://metadata.io/developers/tools/check_campaign_launch_readiness) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `channel` | string | required | The channel to connect. Must be one of: linkedin, meta (for Facebook/Instagram), google, reddit, x (for Twitter)one of: `linkedin`, `meta`, `google`, `reddit`, `x`, `facebook`, `instagram`, `twitter` |
| `acknowledge_data_access` | boolean |   | Set true to confirm the person you are acting for asked to connect this channel. The response is an OAuth authorization URL that starts a credential grant into their Metadata account. Without this the call is refused. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/connect_channel) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `data` | object | required | Budget group configuration |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_budget_group) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_data` | object | required | Complete campaign configuration data |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_campaign) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_data` | object | required | Complete Channel First / Native Structure (N×N×N) campaign configuration. Each channel takes a `containers` list; each container groups one audience with an `ad_offers` list of {ad, offer} pairs. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_native_structure_campaign) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `offer_type` | string | required | Type of offer to createone of: `Lead Gen`, `Landing Page` |
| `data` | object | required | Offer configuration data. Required fields depend on offer_type and channel - see description for details. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_offer) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `channel` | string | required | The channel to disconnect. Must be one of: reddit, facebook, linkedin, twitter, google, instagramone of: `reddit`, `facebook`, `linkedin`, `twitter`, `google`, `instagram` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/disconnect_channel) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The wizard/campaign ID of the campaign to duplicate. Must be in status Launched, Launching, Editing, or Draft. |
| `name` | string |   | Name for the new (copied) campaign. Must be unique on the account and <= 255 chars. Omit to auto-generate '<original name>_copy_<timestamp>'. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/duplicate_campaign) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domain` | string | required | Company website URL or domain. Examples: 'snowflake.com', 'www.servicenow.com' |
| `offer_type` | string | required | Type of offer content to locate. Drives which paths are probed and which keywords score higher.one of: `case_study`, `demo`, `whitepaper`, `roi_calculator`, `guide`, `report`, `ebook`, `webinar` |
| `topic` | string |   | Optional topic keywords to bias scoring (e.g., 'fintech', 'servicenow integration', 'data warehousing'). Improves hit rate when the domain has many offers of the same type. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/find_offer_url) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | The name of the budget group to search for. Example: 'Brand' |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_budget_group) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The wizard campaign ID to retrieve details for |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_campaign_by_wizard_id) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_ids` | array |   | Wizard campaign ids to read. Omit to scan the account. |
| `country_names` | array |   | Filter to campaigns targeting these countries, e.g. ["Germany", "Austria"]. |
| `max_campaigns` | integer |   | Cap on campaigns read when scanning (default 25, max 100). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_campaign_targeting_locations) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string |   | The name of the offer to search for. Example: 'AI Marketing Audit Demo'. If omitted, returns a list of all available offers. |
| `offer_id` | integer |   | Exact offer id. PREFER THIS over `name` whenever you have an id: a name lookup returns the first search match, so offers sharing a prefix (a template name plus a random suffix, which is how offers get named here) can resolve to the wrong one silently. Takes precedence when both are given. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_offer) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the draft campaign to launch |

[Full page, schema and recorded response](https://metadata.io/developers/tools/launch_campaign) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `sort_by` | string |   | Field to sort budget groups by. Default: totalActiveExperimentsone of: `totalActiveExperiments`, `monthlyCap`, `averageDailyBudgetPerExperiment`, `spent`, `totalBudget`, `endDate`, `startDate`, `leads`, `cpl` |
| `sort_order` | string |   | Sort order - 'asc' (ascending) or 'desc' (descending). Default: descone of: `asc`, `desc` |
| `page` | integer |   | Page number for pagination (0-based). Default: 0 |
| `size` | integer |   | Number of results per page. Default: 10 |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_budget_groups) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `page` | integer |   | 0-based page index. Default: 0 |
| `size` | integer |   | Results per page. Default: 25 |
| `sort_by` | string |   | Field to sort by. Default: createdDateone of: `createdDate`, `startDate`, `endDate`, `name`, `budget`, `spent`, `leads`, `cpl`, `cpc`, `ctr`, `impressions`, `clicks` |
| `sort_order` | string |   | Sort order. Default: descone of: `asc`, `desc` |
| `status` | string |   | Campaign-level status filter. Comma-separated subset of Draft, Launched, Finished. Omit to include all three. Combine with experiment_statuses to mirror the UI tabs (e.g. Active tab = status=Launched + experiment_statuses=Active,WithoutSpend). |
| `experiment_statuses` | string |   | Experiment-level status filter. Comma-separated subset of Active, WithoutSpend, Paused, Completed, Failed. Omit to include all five. |
| `visibility` | string |   | Optional: filter by campaign visibility. Omit to include all.one of: `VISIBLE`, `ARCHIVED` |
| `name` | string |   | Optional: server-side name substring filter. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_wizard_campaigns) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the campaign to manage |
| `action` | string | required | The action to perform: 'pause' to stop the campaign, 'restart' to resume itone of: `pause`, `restart` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/manage_campaign) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `experiment_id` | integer | required | The experiment ID to pause or restart (experimentId from search_experiments). |
| `action` | string | required | The action to perform: 'pause' to stop the experiment, 'restart' to resume itone of: `pause`, `restart` |
| `confirm_budget_impact` | boolean |   | Restart only. Set true ONLY after the user explicitly confirmed the budget-group impact returned by a previous manage_experiment call with status='requires_confirmation'. |
| `auto_pause_ignore_historical_data` | boolean |   | Restart only. When the experiment was auto-paused for low performance, true tells the optimizer to ignore the historical performance data that caused the pause. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/manage_experiment) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the campaign |
| `channels` | array | required | List of channels to disable from the campaign. Example: ["FACEBOOK", "GOOGLE_ADS"] |

[Full page, schema and recorded response](https://metadata.io/developers/tools/remove_channels_from_campaign) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the campaign |
| `channel_offers` | object | required | Map of channel type to list of offer names (Lead Gen form or Landing Page) to remove. Example: {"FACEBOOK": ["Demo Form"], "GOOGLE_ADS": ["Pricing LP"]} |

[Full page, schema and recorded response](https://metadata.io/developers/tools/remove_offers_from_campaign) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_names` | array | required | Array of campaign names or partial names to search for (case-insensitive, partial matching) |

[Full page, schema and recorded response](https://metadata.io/developers/tools/search_campaigns_by_names) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `query` | string | required | Natural-language description of the campaign you are building, e.g. "lead gen campaign targeting IT decision makers", "top of funnel awareness push for a new product launch". |
| `channel` | any |   | Optional exact filter — "linkedin", "facebook", "google_ads", "instagram". Omit to search every channel. |
| `ad_format` | any |   | Optional exact filter — "image", "video", "document", "carousel", "text". |
| `audience_type` | any |   | Optional exact filter, e.g. "firmographic_include", "linkedin_retargeting", "native_targeting_dynamic". |
| `bid_strategy` | any |   | Optional exact filter, e.g. "auto_bid", "manual_bid", "metadata_bid_agent". |
| `num_results` | integer |   | How many recipes to return (default 5). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/search_experiment_recipes) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `search_name` | string |   | The experiment or campaign name to search for (partial, case-insensitive matching). Optional - omit to skip name filtering. |
| `budget_group_ids` | array |   | Optional array of budget group IDs to filter experiments. Only returns experiments that belong to these budget groups. |
| `launched_experiment_statuses` | array |   | Optional array of experiment statuses to filter by. Valid values: Active, WithoutSpend, Paused, Completed, Failed, Disconnected |
| `page` | integer |   | Page number for pagination (default: 0) |
| `size` | integer |   | Number of results per page (default: 5) |
| `sort` | string |   | Sort criteria in format 'field,direction' (e.g., 'name,asc') |

[Full page, schema and recorded response](https://metadata.io/developers/tools/search_experiments) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `budgets` | object | required | Dictionary mapping experiment IDs to new daily budget values. Keys are experiment IDs (integers or strings), values are budget amounts (numbers or strings with comma/dot separators). Example: {'12345': 100.50, '12346': '150,75'} |

[Full page, schema and recorded response](https://metadata.io/developers/tools/update_experiments_daily_budgets) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the wizard campaign |
| `objective` | string |   | Reddit native objective. IMPRESSIONS = Brand awareness and Reach; CLICKS = Traffic (the only objective allowed on Lead Gen campaigns); VIDEO_VIEWABLE_IMPRESSIONS_6S = Video Views 6s (video-only channels).one of: `IMPRESSIONS`, `CLICKS`, `VIDEO_VIEWABLE_IMPRESSIONS_6S` |
| `allow_comments` | boolean |   | Allow Redditors to comment on the promoted post. Platform default is true. |
| `placements` | object |   | Where the ads serve. At least one placement must stay selected; conversations is forced off when the channel has video ads. |
| `conversion_pixel_id` | string |   | Reddit conversion pixel id (created in Reddit Ads Manager). Empty string clears the pixel. |
| `bid_amount` | number |   | Manual bid amount, applied only when the effective objective uses MANUAL_BID (IMPRESSIONS / Video Views). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/update_reddit_channel_settings) · [machine index](https://metadata.io/developers/tools.json)

## Ads and creative 27

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `ids` | array | required | Ad id(s) to archive. At least one integer required; pass multiple to archive in bulk. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/archive_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `adName` | string | required | Ad name. Required, max 50 chars. |
| `headline` | string | required | Headline shared across all cards. Required, max 300. |
| `cards` | array | required | 2 to 6 carousel cards. Each card needs a distinct image (no duplicates). |
| `text` | string |   | Optional body text. Max 2000. |
| `thumbnailLibraryId` | integer |   | Optional thumbnail image library id. |
| `completionStatus` | string |   | DRAFT (default) persists locally without publishing; COMPLETED finalizes the ad.one of: `DRAFT`, `COMPLETED` |
| `id` | integer |   | Include to UPDATE an existing carousel ad; omit to CREATE. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_carousel_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `id` | integer |   | Existing convo ad ID — include to UPDATE; omit to CREATE. |
| `name` | string | required | Ad name in the platform library (max 50 chars). |
| `senderId` | string | required | LinkedIn sender ID. MUST come from get_linkedin_senders. |
| `senderName` | string | required | Display name matching senderId from get_linkedin_senders. |
| `headlineText` | string | required | Subject line shown above the message thread. |
| `bannerCreativeLibraryId` | integer |   | Optional: imageLibraryId of the banner image. Upload first via upload_image_creative. |
| `completionStatus` | string |   | Defaults to DRAFT.one of: `DRAFT`, `COMPLETED` |
| `flowId` | integer |   | LinkedIn convo flow version. Defaults to 7 — keep the default unless told otherwise. |
| `templateId` | integer |   | LinkedIn convo template ID. Defaults to 1 — keep the default unless told otherwise. |
| `steps` | array | required | Ordered list of conversation steps. MUST include stepId=1 as the entry. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_convo_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `id` | integer |   | Existing Document Ad ID — include to UPDATE; omit to CREATE. |
| `name` | string | required | Ad name in the platform library (max 50 characters). |
| `libraryId` | integer | required | Integer id of the DOCUMENT creative in the library (contentType=DOCUMENT). Get it from search_library_creatives_by_name(contentTypes="DOCUMENT"). NOT an image/video id. |
| `headline` | string | required | Headline shown with the document (max 200 characters). |
| `text` | string | required | Introductory text shown with the document (max 3000 characters). |
| `ctaType` | string |   | Call-to-action. Defaults to UNLOCK_FULL_DOCUMENT (the document-gate CTA).one of: `UNLOCK_FULL_DOCUMENT` |
| `maxPreviewPages` | integer |   | How many document pages are previewable before the unlock gate. Defaults to 1. |
| `completionStatus` | string |   | Defaults to DRAFT. Use COMPLETED only when every required field is final.one of: `DRAFT`, `COMPLETED` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_document_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `id` | integer |   | The existing ad ID to update. If omitted, a new ad will be created. |
| `name` | string | required | The name/label for the ad in Metadata platform (max 50 characters) |
| `headlines` | array | required | List of headline texts for the Google Ads ad (minimum 3, maximum 15 headlines, each max 30 characters) |
| `descriptions` | array | required | List of description texts for the Google Ads ad (2 to 4 descriptions). CRITICAL #1 FAILURE MODE: each description MUST be ≤ 90 characters — this is enforced by maxLength schema validation AND by server-side truncation. Going over 90 means either (a) the call is rejected before it runs, or (b) the de |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_google_ads_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `ads_data` | array | required | Array of IMAGE ads to create or update. Each item targets one or more of FB/IG/LinkedIn/Reddit; the platform creates one ad row per (ad, channel). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_image_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `id` | integer |   | Existing Message Ad ID — include to UPDATE; omit to CREATE. |
| `name` | string | required | Ad name in the platform library (max 50 characters). |
| `senderId` | string | required | LinkedIn sender ID. MUST come from get_linkedin_senders. Do not invent. |
| `senderName` | string | required | Display name matching senderId, also from get_linkedin_senders. |
| `headlineText` | string | required | Message subject line shown in the recipient's inbox (max 60 characters). |
| `messageText` | string | required | Message body (max 2000 characters). Supports LinkedIn personalization macros — ONLY %FIRSTNAME%, %LASTNAME%, %COMPANYNAME%, %JOBTITLE%, %INDUSTRY%. Any other %...% token is rejected by the platform validator. |
| `actionText` | string | required | Call-to-action button label (max 20 characters). |
| `bannerCreativeLibraryId` | integer |   | Optional: imageLibraryId of the banner image shown above the message. Upload the image first via upload_image_creative and pass the returned ID. Omit to skip the banner. |
| `completionStatus` | string |   | Defaults to DRAFT. Use COMPLETED only when every required field is final.one of: `DRAFT`, `COMPLETED` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_linkedin_message_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `id` | integer |   | The existing ad ID to update. If omitted, a new ad will be created. |
| `name` | string | required | The name/label for the ad in Metadata platform (max 50 characters) |
| `headlines` | array | required | List of headline texts for the Microsoft Ads ad (minimum 3, maximum 15 headlines, each max 30 characters). Every headline must be DISTINCT — the platform rejects the ad if two share the same text — and must not contain '!'. |
| `descriptions` | array | required | List of description texts for the Microsoft Ads ad (2 to 4 descriptions — 2 is the platform minimum, a single-description ad is rejected). Each description MUST be 90 characters or fewer and MUST be distinct from the others. Count every character (incl. spaces/punctuation/emoji); target 70-85 chars |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_microsoft_ads_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `ads_data` | array | required | Array of VIDEO ads to create or update. Each item targets one or more of FB/IG/LinkedIn/Reddit; the platform creates one ad row per (ad, channel). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_update_video_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `image_source` | string | required | URL of the creative image to edit. Must be a valid accessible image URL (PNG, JPG, WebP). Can be a URL returned by a previous generation or edit. |
| `edit_instruction` | string | required | Natural language description of the desired edit(s). Can include multiple changes in one request. Examples: 'Replace the robot with a dashboard', 'Change headline to BOOST ROI and make CTA say GET STARTED', 'Add a +50% ROI badge in the corner' |
| `domain` | string | required | Company domain for brand context. Used to fetch brand DNA for consistency. Examples: 'metadata.io', 'bloomreach.com' |

[Full page, schema and recorded response](https://metadata.io/developers/tools/edit_brand_creative) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `creative_id` | integer |   | creative id to be query |

[Full page, schema and recorded response](https://metadata.io/developers/tools/fetch_creative_details) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `image_source` | string | required | URL of the background image to edit (PNG/JPG/WebP). Typically the flexible creative's current background. |
| `edit_instruction` | string | required | Natural-language description of the fix(es). Can combine several changes in one request. |
| `domain` | string | required | Company domain for brand context (e.g. 'metadata.io'). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/fix_flexible_creative) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domain` | string | required | Company domain to extract brand DNA from. Examples: 'docebo.com', 'metadata.io', 'bloomreach.com'. Do not include protocol (http/https). |
| `headline` | string | required | Primary headline text to display in the creative. Keep to 25 characters or fewer for optimal rendering (hard cap 40 — the image model truncates or garbles longer text). Used to select aligned reference ads and guide visual hierarchy. Examples: 'Boost ROI by 30%', 'AI-Powered Marketing', 'Drive More |
| `instructions` | string | required | Natural language instructions describing the desired creative. Will be enhanced with brand DNA patterns including proven layouts, CTAs, colors, and tones. Examples: 'Create a professional B2B ad with clean design', 'Generate announcement for new AI feature launch', 'Design case study visual with mod |
| `platform` | string |   | Target platform for the creative. Each platform has specific dimensions, text limits, and best practices that will be automatically applied. Default: 'linkedin'one of: `linkedin`, `facebook`, `instagram`, `display`, `general` |
| `include_logo` | boolean |   | Whether to include a logo overlay on the generated creative. Set to false to get the raw creative without any logo. Default: true |
| `include_cta` | boolean |   | Whether to render a call-to-action (button or styled text link) in the creative. Set to false for surfaces that must not contain a CTA, e.g. stills that seed video ads, where the channel's ad unit provides the real CTA. Default: true |
| `logo_position` | string |   | Force a specific logo position instead of using AI-recommended placement. If not provided, an AI model analyzes the creative to find the optimal position.one of: `top-left`, `top-right`, `bottom-left`, `bottom-right` |
| `logo_size_percent` | number |   | Logo width as a percentage of the image width (e.g., 15 means the logo occupies 15% of the image width). If not provided, the AI recommends an optimal size. Typical range: 10-30. |
| `logo_url` | string |   | Optional direct URL to a logo image (e.g. the URL of a logo the user just uploaded in chat). When set, THIS logo is overlaid for this creative instead of the brand kit's logo or the one from Brandfetch. Use it when the user says things like 'use this logo' or 'use the logo I uploaded'. The uploaded |
| `use_website_background` | boolean |   | Use the brand website's background color as the creative's dominant background; brand primary colors then appear as accents (CTA button, shapes, highlights). Default: true. Set false when the user wants a brand-colored or model-chosen background instead. Silently ignored when the brand kit has no re |

[Full page, schema and recorded response](https://metadata.io/developers/tools/generate_brand_creative) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domain` | string | required | Company website URL or domain |
| `brand_name` | string |   | Optional brand name override |
| `sample_ad_urls` | array |   | Optional ad image URLs to analyze (max 5) |
| `force_regenerate` | boolean |   | If True, regenerate brand kit even if one already exists. Default: False |

[Full page, schema and recorded response](https://metadata.io/developers/tools/generate_brand_kit) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domain` | string | required | Company domain for brand DNA (e.g. 'metadata.io'). No protocol. |
| `instructions` | string | required | Natural-language direction for the background scene and overall creative (e.g. 'clean B2B scene for an AI analytics launch'). |
| `platform` | string |   | Target platform (sets the default aspect ratio). Default: 'linkedin'.one of: `linkedin`, `facebook`, `instagram`, `reddit`, `display`, `general` |
| `aspect_ratio` | string |   | Canvas shape, overriding the one 'platform' implies. Pass this whenever the user names a size or shape: '1:1' for square (e.g. 1080x1080), '16:9' for wide/landscape, '9:16' for a full-height story, '4:5' for portrait. Omit to keep the platform's default shape.one of: `1:1`, `16:9`, `9:16`, `4:5` |
| `headline` | string |   | Headline copy to place as an editable layer. |
| `subheadline` | string |   | Optional subheadline copy. |
| `body` | string |   | Optional supporting body copy. Pass ONLY when the user explicitly asked for body copy — extra layers crowd the layout. |
| `cta` | string |   | Optional call-to-action button text (e.g. 'Learn more'). |
| `disclaimer` | string |   | Optional fine-print/disclaimer copy. Pass ONLY when the user explicitly asked for a disclaimer. |
| `include_logo` | boolean |   | Add a brand logo layer (resolved from the brand kit). Default: true. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/generate_flexible_brand_creative) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `ids` | object | required | Ad ID(s) to get details for. Can be: single integer (182124) or comma-separated string ('182124,182123'). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_ad_details) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domain` | string | required | Company website URL or domain. Examples: 'metadata.io', 'www.bloomreach.com', 'https://example.com' |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_brand_kit) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domain` | string | required | Company domain for brand DNA (e.g. 'metadata.io'). No protocol. |
| `instructions` | string | required | Direction for the new background scene. |
| `platform` | string |   | Target platform (sets the default aspect ratio). Default: 'linkedin'.one of: `linkedin`, `facebook`, `instagram`, `reddit`, `display`, `general` |
| `aspect_ratio` | string |   | Pass the creative's own canvas.aspect_ratio so the new background keeps its shape. Omitting it on a non-default canvas reshapes the creative and the existing layers no longer fit.one of: `1:1`, `16:9`, `9:16`, `4:5` |
| `image_source` | string |   | Optional URL of the current background to guide a same-style regeneration (image-to-image). Omit for a fresh scene. |
| `background_hex` | string |   | Optional 6-digit hex to pin the dominant background color (e.g. '#0A2540'). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/regenerate_flexible_background) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the campaign |
| `channel_ads` | object | required | Map of channel type to list of ad names to remove. Example: {"LINKEDIN": ["Ad A"], "FACEBOOK": ["Ad B"]} |

[Full page, schema and recorded response](https://metadata.io/developers/tools/remove_ad_from_campaign) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `design` | object | required | The layered creative document to flatten (canvas, background, layers, brand) — the same JSON the editor edits. |
| `name` | string |   | Optional library name for the rendered image. Omit it and one is derived from the doc as `<brand-domain>-<channel>-<width>x<height>.png`, which is normally what you want. Must end in a file extension. |
| `upload_to_library` | boolean |   | Push the rendered PNG to the creatives library. Default: true. |
| `archive_library_image_id` | string |   | Optional. The library image id this save supersedes (the creative's previous render). Archived on the platform ONLY after the new upload succeeds, so re-saving an editable creative retires the old PNG instead of piling up dead library images. Never affects an ad already built from it. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/render_flexible_creative) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `ad_names` | array | required | Array of ad names or partial names to search for (case-insensitive, partial matching) |
| `page` | integer |   | Zero-based page index (default: 0). Page numbering starts at 0. |
| `size` | integer |   | Results per page (default: 25, recommended max: 25). Larger windows blow LLM token budgets — only request more when the caller actually needs it. |
| `sort` | string |   | Spring sort clause, e.g. 'createdDate,desc' (default), 'id,desc', or 'name,asc'. |
| `status` | string |   | Which status bucket to return. 'active' (default) is the prior active-only behaviour. 'archived' returns ONLY archived (soft-deleted) ads, which is what you need to find an ad's id for unarchive_ad. 'all' returns both active and archived in one response. Maps to the platform's status query param semone of: `active`, `archived`, `all` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/search_ads_by_names) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `creativeName` | string |   | Name or partial name of the creative to search for. Supports partial matching and is case-insensitive. Omit to list all creatives. |
| `page` | integer |   | Zero-based page index (default: 0). |
| `size` | integer |   | Results per page (default: 10, recommended max: 10). Larger windows blow LLM token budgets — only request more when the caller actually needs it. |
| `contentTypes` | string |   | Filter by content types (comma-separated). Supported values: IMAGE,VIDEO,GIF,DOCUMENT. Example: IMAGE,VIDEO or IMAGE%2CVIDEO%2CGIF%2CDOCUMENT |

[Full page, schema and recorded response](https://metadata.io/developers/tools/search_library_creatives_by_name) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `ids` | array | required | Ad id(s) to unarchive. At least one integer required; pass multiple to restore in bulk. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/unarchive_ad) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `company_url` | string | required | Company website URL or domain (e.g. 'ambient.ai'). |
| `long_description` | string |   | Company description for marketing use. |
| `logo_url` | string |   | Direct URL to a single company logo image (back-compat; prefer logo_urls). Setting a permanent brand logo requires elevated Metadata permissions. |
| `logo_urls` | array |   | One or more direct URLs to logo images to set as the brand's permanent logo(s). Each uploaded logo is automatically expanded into clean, persisted variants (transparent, high-res, and both a light and dark version when the mark is a single color) so generated creatives have multiple usable options. |
| `remove_old_logos` | boolean |   | When true (default), replace the brand's existing logos with the provided ones; when false, append to them. |
| `search_keywords` | array |   | SEO/search keywords for the brand. |
| `website_background` | string |   | 6-digit hex color (e.g. '#FFFFFF') of the brand website's background. generate_brand_creative uses it as the default dominant background for ads (use_website_background). Set it when the user wants ads to match their site's background or the auto-detected value is wrong. |
| `colors` | array |   | Legacy flat color list. Each: {hex (with #), type, name?}. |
| `fonts` | array |   | Legacy flat font list. Each: {name, type}. |
| `primary_colors` | array |   | Primary color palette. |
| `accent_colors` | array |   | Accent color palette. |
| `extended_palette` | array |   | Extended grayscale palette. |
| `semantic_colors` | array |   | Semantic/status colors. |
| `primary_font` | string |   | Primary font family name. |
| `primary_font_usage` | string |   | Primary font usage description. |
| `secondary_font` | string |   | Secondary/display font family name. |
| `secondary_font_usage` | string |   | Secondary font usage description. |
| `headline_font` | string |   | Headline font family. |
| `headline_weight` | string |   | Headline font weight. |
| `headline_size` | string |   | Headline font size range. |
| `headline_case` | string |   | Headline text case rule. |
| `headline_linespace` | string |   | Headline line spacing. |
| `headline_letterspace` | string |   | Headline letter spacing. |
| `eyebrow_font` | string |   | Eyebrow font family. |
| `eyebrow_weight` | string |   | Eyebrow font weight. |
| `eyebrow_case` | string |   | Eyebrow text case rule. |
| `eyebrow_linespace` | string |   | Eyebrow line spacing. |
| `eyebrow_letterspace` | string |   | Eyebrow letter spacing. |
| `subtitle_font` | string |   | Subtitle font family. |
| `subtitle_weight` | string |   | Subtitle font weight. |
| `subtitle_linespace` | string |   | Subtitle line spacing. |
| `subtitle_letterspace` | string |   | Subtitle letter spacing. |
| `body_font` | string |   | Body text font family. |
| `body_weight` | string |   | Body text font weight. |
| `body_size` | string |   | Body text font size. |
| `body_linespace` | string |   | Body text line spacing. |
| `body_letterspace` | string |   | Body text letter spacing. |
| `cta_font` | string |   | CTA/button font family. |
| `cta_weight` | string |   | CTA/button font weight. |
| `cta_size` | string |   | CTA/button font size. |
| `cta_linespace` | string |   | CTA/button line spacing. |
| `cta_letterspace` | string |   | CTA/button letter spacing. |
| `logo_on_dark` | string |   | Logo color rule on dark backgrounds. |
| `logo_on_light` | string |   | Logo color rule on light backgrounds. |
| `logo_clear_space` | string |   | Logo clear space rule. |
| `logo_misuse` | array |   | List of logo misuse rules. |
| `button_shape` | string |   | Button shape description. |
| `button_background` | string |   | Button background style. |
| `button_text_color` | string |   | Button text color rule. |
| `button_text_weight` | string |   | Button text weight. |
| `button_text_case` | string |   | Button text case. |
| `button_padding` | string |   | Button padding. |
| `standard_ctas` | array |   | Standard CTA labels. |
| `cta_placement` | string |   | CTA placement guidance. |
| `tagline` | string |   | Primary brand tagline. |
| `tagline_variants` | array |   | Alternative taglines. |
| `tagline_placement` | string |   | Tagline placement guidance. |
| `visual_motifs` | array |   | Brand visual motifs. |
| `promotional_elements` | array |   | Promotional proof points. |
| `tone` | string |   | Brand tone description. |
| `value_propositions` | array |   | Core value propositions. |
| `headline_formulas` | array |   | Headline writing patterns. |
| `proof_points` | array |   | Evidence/social proof items. |
| `product_names` | object |   | Product name mapping (e.g. {platform: 'X', vlm: 'Y'}). |
| `content_hierarchy_order` | array |   | Content element ordering. |
| `content_hierarchy_spacing` | string |   | Section spacing guidance. |
| `content_hierarchy_text_max_width` | string |   | Max text block width. |
| `photography_style` | string |   | Photography style description. |
| `photography_subjects` | array |   | Recommended photo subjects. |
| `photography_treatment` | string |   | Photo treatment rules. |
| `photography_avoid` | string |   | Photography anti-patterns. |
| `dos` | array |   | Brand 'do' rules. |
| `donts` | array |   | Brand 'don't' rules. |
| `primary_layouts` | array |   | Layout system definitions. |
| `channel_linkedin` | object |   | LinkedIn channel config. |
| `channel_facebook` | object |   | Facebook channel config. |
| `channel_display` | object |   | Display ads channel config. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/update_brand_kit) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the wizard campaign |
| `channel` | string | required | Which campaign channel to edit. Meta placements only exist on Facebook and Instagram channels.one of: `FACEBOOK`, `INSTAGRAM` |
| `mode` | string | required | AUTO = automatic placements (Meta decides, clears the manual set). MANUAL = serve only on the placements listed in `placements`.one of: `AUTO`, `MANUAL` |
| `placements` | array |   | Placement codes to serve on. Required when mode=MANUAL (at least one); ignored for AUTO. Companion rules apply — see the tool description. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/update_meta_placements) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `images` | array | required | Array of image URLs to upload to platform |
| `names` | array |   | Optional library name per image, positional against `images`. Pass one whenever you know what the creative is: without it the name is taken from the URL, which for a generated creative is an opaque key like `brand_creative_20260814_211126_66d8a83e.png` and leaves the user unable to tell their creati |

[Full page, schema and recorded response](https://metadata.io/developers/tools/upload_image_creative) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `videos` | array | required | Array of video URLs to upload to the platform library. |
| `thumbnail_library_id` | integer |   | Optional existing imageLibraryId to attach as the video's platform thumbnail. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/upload_video_creative) · [machine index](https://metadata.io/developers/tools.json)

## Ad extensions 18

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The wizard campaign id. |
| `channel` | string | required | Search channel. Ad extensions are a search-channel-only concept.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |
| `extension_ids` | array | required | Internal library extension ids from list_extensions. These are the `id` field, NOT `externalId` (the ad platform's own id). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/add_extensions_to_native_campaign) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `image_library_id` | integer | required |   |
| `business_name` | string |   |   |
| `domain_name` | string |   |   |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_google_business_logo_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `callout_text` | string | required | Callout snippet. 1-25 characters. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_google_callout_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `image_library_ids` | array | required | 1-20 image-library IDs. |
| `alternative_text` | string |   |   |
| `display_text` | string |   |   |
| `destination_url` | string |   |   |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_google_image_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `headline` | string | required |   |
| `business_name` | string | required |   |
| `description` | string |   |   |
| `email_lead_form_user_input_types` | array | required |   |
| `contact_lead_form_user_input_types` | array |   |   |
| `work_lead_form_user_input_types` | array |   |   |
| `privacy_policy_url` | string | required |   |
| `post_submit_headline` | string | required |   |
| `post_submit_description` | string | required |   |
| `post_submit_call_to_action_type` | string | required | one of: `VISIT_SITE`, `DOWNLOAD`, `LEARN_MORE`, `SHOP_NOW` |
| `url` | string |   | Optional thank-you-page URL. |
| `call_to_action_type` | string | required | one of: `APPLY_NOW`, `BOOK_NOW`, `CONTACT_US`, `DOWNLOAD`, `GET_INFO`, `GET_OFFER`, `GET_QUOTE`, `GET_STARTED`, `JOIN_NOW`, `LEARN_MORE`, `REGISTER`, `REQUEST_DEMO` |
| `call_to_action_description` | string | required |   |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_google_lead_form_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `price_qualifier` | string | required | Price qualifier shown before the price.one of: `UNSPECIFIED`, `FROM`, `UP_TO`, `AVERAGE` |
| `price_offerings` | array | required | 3-8 price offerings. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_google_price_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `occasion` | string | required | one of: `NONE`, `BACK_TO_SCHOOL`, `BLACK_FRIDAY`, `BOXING_DAY`, `CARNIVAL`, `CHINESE_NEW_YEAR`, `CHRISTMAS`, `CYBER_MONDAY`, `DIWALI`, `EASTER`, `EID_AL_ADHA`, `EID_AL_FITR` |
| `url` | string | required |   |
| `item` | string | required |   |
| `category_type` | string | required | one of: `MONETARY`, `UP_TO_MONETARY`, `PERCENT`, `UP_TO_PERCENT` |
| `category_amount` | number |   | USD amount; supply when category_type is MONETARY or UP_TO_MONETARY. |
| `category_percent` | number |   | Percent (≤100); supply when category_type is PERCENT or UP_TO_PERCENT. |
| `details_type` | string | required | one of: `NONE`, `ON_ORDERS_OVER`, `PROMO_CODE` |
| `details_promo_code` | string |   | Promo code; supply when details_type is PROMO_CODE. |
| `details_amount` | number |   | Threshold USD amount; supply when details_type is ON_ORDERS_OVER. |
| `start_date` | string | required | ISO-8601 "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'". Future or present. |
| `end_date` | string | required | ISO-8601 "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'". Future or present. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_google_promotion_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `url` | string | required | Destination URL the sitelink points to (non-blank). |
| `link_text` | string | required | Visible link text. 1-25 characters. |
| `description1` | string | required | First description line. 1-35 characters. |
| `description2` | string | required | Second description line. 1-35 characters. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_google_sitelink_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `header` | string | required | Snippet header. 1-25 characters. |
| `values` | array | required | 3-10 snippet values, each 1-25 characters. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_google_structured_snippet_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `image_library_id` | integer | required |   |
| `business_name` | string |   |   |
| `domain_name` | string |   |   |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_microsoft_business_logo_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `callout_text` | string | required | Callout snippet. 1-25 characters. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_microsoft_callout_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `image_library_ids` | array | required | 1-20 image-library IDs. |
| `alternative_text` | string |   |   |
| `display_text` | string |   |   |
| `destination_url` | string |   |   |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_microsoft_image_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `price_qualifier` | string | required | Price qualifier shown before the price.one of: `UNSPECIFIED`, `FROM`, `UP_TO`, `AVERAGE` |
| `price_offerings` | array | required | 3-8 price offerings. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_microsoft_price_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `occasion` | string | required | one of: `NONE`, `BACK_TO_SCHOOL`, `BLACK_FRIDAY`, `BOXING_DAY`, `CARNIVAL`, `CHINESE_NEW_YEAR`, `CHRISTMAS`, `CYBER_MONDAY`, `DIWALI`, `EASTER`, `EID_AL_ADHA`, `EID_AL_FITR` |
| `url` | string | required |   |
| `item` | string | required |   |
| `category_type` | string | required | one of: `MONETARY`, `UP_TO_MONETARY`, `PERCENT`, `UP_TO_PERCENT` |
| `category_amount` | number |   | USD amount; supply when category_type is MONETARY or UP_TO_MONETARY. |
| `category_percent` | number |   | Percent (≤100); supply when category_type is PERCENT or UP_TO_PERCENT. |
| `details_type` | string | required | one of: `NONE`, `ON_ORDERS_OVER`, `PROMO_CODE` |
| `details_promo_code` | string |   | Promo code; supply when details_type is PROMO_CODE. |
| `details_amount` | number |   | Threshold USD amount; supply when details_type is ON_ORDERS_OVER. |
| `start_date` | string | required | ISO-8601 "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'". Future or present. |
| `end_date` | string | required | ISO-8601 "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'". Future or present. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_microsoft_promotion_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `url` | string | required | Destination URL the sitelink points to (non-blank). |
| `link_text` | string | required | Visible link text. 1-25 characters. |
| `description1` | string | required | First description line. 1-35 characters. |
| `description2` | string | required | Second description line. 1-35 characters. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_microsoft_sitelink_extension) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `header` | string | required | Snippet header. 1-25 characters. |
| `values` | array | required | 3-10 snippet values, each 1-25 characters. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_microsoft_structured_snippet_extension) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `channel` | string | required | Search channel. Ad extensions are a search-channel-only concept.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |
| `types` | array |   | Optional extension-type filter, e.g. ["SITELINK"]. |
| `name` | string |   | Optional name filter. Names are auto-derived by the platform, not user-chosen, so prefer filtering by `types`. |
| `page` | integer |   | 0-based page index. Defaults to 0. |
| `size` | integer |   | Page size. Defaults to 50. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_extensions) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The wizard campaign id. |
| `channel` | string | required | Search channel. Ad extensions are a search-channel-only concept.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |
| `extension_ids` | array | required | Internal library extension ids from list_extensions. These are the `id` field, NOT `externalId` (the ad platform's own id). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/remove_extensions_from_native_campaign) · [machine index](https://metadata.io/developers/tools.json)

## Paid search 18

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `negativeListIds` | array | required | IDs of the existing negative keyword lists to extend (from list_negative_keywords_list). |
| `keywords` | array | required | Keywords to add to every list in negativeListIds. Each item is either a plain string or {text, match_type}. |
| `match_type` | string |   | Default match type, used when an item is a plain string or an object that omits match_type. Default PHRASE.one of: `EXACT`, `PHRASE`, `BROAD` |
| `channel` | string |   | Ad channel scope. Both search channels are supported. These are PER-CHANNEL resources: GOOGLE_ADS and MICROSOFT_ADS hold separate sets, and one is invisible to the other. Defaults to GOOGLE_ADS when the user does not say which.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/add_keywords_to_negative_lists) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaignIds` | array | required | Wizard campaign ids of the LIVE (already launched) campaigns to update. Pass every campaign the user named in one call. Draft campaigns are skipped with a reason. |
| `listNames` | array |   | Names of existing negative keyword lists to attach. Matched exactly (case-insensitive) against the account library; an unmatched name is reported, never substituted. |
| `listIds` | array |   | IDs of existing negative keyword lists to attach, as returned by list_negative_keywords_list. Can be combined with listNames. |
| `mode` | string |   | 'add' (default) merges with the lists already on the campaign. 'replace' makes the campaign's negative lists exactly the ones requested, detaching the rest — only for an explicit user request.one of: `add`, `replace` |
| `channel` | string |   | Ad channel scope. Only GOOGLE_ADS is supported — the platform's live-edit endpoint is Google-only.one of: `GOOGLE_ADS` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/add_negative_keyword_lists_to_live_campaigns) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `keywords` | array | required | Array of keyword strings to create. Example: ["goku", "ssj", "ssj1"] |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_keywords) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string | required | Name of the negative keywords list (string). Example: "Competitor Brands", "Low Intent Keywords" |
| `keywords` | array | required | Array of keyword strings to block. Example: ["raichu", "blastoise", "charizard"] |
| `match_type` | string | required | Match type for all keywords. Options: EXACT (exact match), PHRASE (phrase match), BROAD (broad match). Example: 'EXACT'one of: `EXACT`, `PHRASE`, `BROAD` |
| `channel` | string |   | Ad channel scope. Both search channels are supported. These are PER-CHANNEL resources: GOOGLE_ADS and MICROSOFT_ADS hold separate sets, and one is invisible to the other. Defaults to GOOGLE_ADS when the user does not say which.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_negative_keywords_list) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `listIds` | array | required | IDs of the negative keyword lists to delete (from list_negative_keywords_list). |
| `channel` | string |   | Ad channel scope. Both search channels are supported. These are PER-CHANNEL resources: GOOGLE_ADS and MICROSOFT_ADS hold separate sets, and one is invisible to the other. Defaults to GOOGLE_ADS when the user does not say which.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/delete_negative_keyword_lists) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `sourceListId` | integer | required | Id of the negative keyword list to copy, as returned by list_negative_keywords_list. |
| `sourceChannel` | string |   | Channel the source list lives on. Default GOOGLE_ADS.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |
| `targetChannel` | string |   | Channel to create the copy on. Must differ from sourceChannel. Default MICROSOFT_ADS.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |
| `name` | string |   | Optional name for the new list. Defaults to "<source name> (<target>)", e.g. "Competitor Brands (Microsoft)". |
| `dryRun` | boolean |   | When true, preview the copy (keyword count + BROAD-to-PHRASE conversions) without creating the list. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/duplicate_negative_keywords_list) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `startDate` | string | required | Start date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: '2025-01-01T00:00:00.000Z' |
| `endDate` | string | required | End date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: '2025-12-31T23:59:59.999Z' |

[Full page, schema and recorded response](https://metadata.io/developers/tools/experiments_keywords_stats) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `listId` | integer | required | ID of the negative keyword list (from list_negative_keywords_list). |
| `text` | string |   | Optional substring filter on keyword text. |
| `page` | integer |   | 0-based page index. Default 0. |
| `size` | integer |   | Rows per page. Default 25, max 100. |
| `sort` | string |   | Sort criteria in format '<field>,<direction>'. Default 'text,asc'. |
| `channel` | string |   | Ad channel scope. Both search channels are supported. These are PER-CHANNEL resources: GOOGLE_ADS and MICROSOFT_ADS hold separate sets, and one is invisible to the other. Defaults to GOOGLE_ADS when the user does not say which.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_negative_keywords_list_details) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `keywordOrExperimentName` | string | required | Search term to filter results by keyword name or experiment name. |
| `page` | integer |   | Page number for pagination (0-based). Default is 0. |
| `size` | integer |   | Number of items per page. Default is 10. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_experiment_keywords) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | object |   | Optional keyword name(s) to search for. Can be a single string or array of strings. Supports partial matching. Omit to list all keywords. |
| `archived` | boolean |   | Filter by archived status. Set to false to show active keywords (default), true to include archived keywords. |
| `page` | integer |   | Page number for pagination (0-based indexing). Default is 0 for the first page. |
| `size` | integer |   | Number of items per page (default: 25, recommended: 25-100). |
| `sort` | string |   | Sort criteria in format: field,direction. Options: avgMonthlySearches, lowerPageBid, higherPageBid, name, modifiedDate. Direction: desc (descending) or asc (ascending). Default: modifiedDate,descone of: `avgMonthlySearches,desc`, `avgMonthlySearches,asc`, `lowerPageBid,desc`, `lowerPageBid,asc`, `higherPageBid,desc`, `higherPageBid,asc`, `name,desc`, `name,asc`, `modifiedDate,desc`, `modifiedDate,asc` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_keywords) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | object |   | Optional negative keywords list name(s) to search for. Can be a single string or array of strings. Supports partial matching. Omit to list all negative keywords lists. |
| `channel` | string |   | Ad channel scope. Both search channels are supported. These are PER-CHANNEL resources: GOOGLE_ADS and MICROSOFT_ADS hold separate sets, and one is invisible to the other. Defaults to GOOGLE_ADS when the user does not say which.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_negative_keywords_list) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `searchTerm` | string |   | Optional substring filter on the search term text. |
| `experiment` | string |   | Optional experiment name substring filter. |
| `keyword` | string |   | Optional matched-keyword substring filter. |
| `matchType` | array |   | Optional subset of match types to include. |
| `startDate` | string |   | Optional ISO-8601 timestamp lower bound (e.g. 2026-06-01T00:00:00.000Z). |
| `endDate` | string |   | Optional ISO-8601 timestamp upper bound (e.g. 2026-06-30T23:59:59.999Z). |
| `page` | integer |   | 0-based page index. Default 0. |
| `size` | integer |   | Rows per page. Default 12 (kept small to limit chat-context tokens), max 100. |
| `sort` | string |   | Sort criteria in format '<field>,<direction>'. Default 'clicks,desc'. Sortable fields: searchTerm, matchType, experiment, addedExcluded, keyword, impressions, clicks, ctr, averageCpc, spent, conversions, costPerConversion. |
| `channel` | string |   | Ad channel scope. Both search channels are supported. These are PER-CHANNEL resources: GOOGLE_ADS and MICROSOFT_ADS hold separate sets, and one is invisible to the other. Defaults to GOOGLE_ADS when the user does not say which.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_search_terms) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `keywordExternalId` | integer | required | The external ID of the keyword to pause. |
| `wizExperimentId` | integer | required | The experiment ID where the keyword is running. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/pause_experiment_keyword) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the campaign |
| `channel_id` | integer |   | Optional fast-path: numeric id of the GOOGLE_ADS channel on this campaign. When provided, the tool skips the full-campaign GET and fetches only this channel's keyword list. Use it when you already have the id from a recent campaign read; omit it and the tool resolves the channel by type. |
| `channel_keywords` | object |   | Map of channel type to list of positive keyword group names to remove. Only GOOGLE_ADS is supported. Example: {"GOOGLE_ADS": ["CRM Keywords"]} |
| `channel_negative_keyword_lists` | object |   | Map of channel type to list of negative keyword list names to detach from the channel. Only GOOGLE_ADS is supported. Example: {"GOOGLE_ADS": ["Competitor Brands"]} |

[Full page, schema and recorded response](https://metadata.io/developers/tools/remove_keywords_from_campaign) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `listId` | integer | required | ID of the negative keyword list (from list_negative_keywords_list). |
| `keywords` | array | required | Exact keyword texts to remove. Case-sensitive whole-text match. |
| `channel` | string |   | Ad channel scope. Both search channels are supported. These are PER-CHANNEL resources: GOOGLE_ADS and MICROSOFT_ADS hold separate sets, and one is invisible to the other. Defaults to GOOGLE_ADS when the user does not say which.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/remove_keywords_from_negative_list) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `keywordExternalId` | integer | required | The external ID of the keyword to restart. |
| `wizExperimentId` | integer | required | The experiment ID where the keyword is running. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/restart_experiment_keyword) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the wizard campaign. |
| `channel` | string | required | Which search channel on the campaign to update. Final URL Suffix is only supported on these two.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |
| `final_url_suffix` | string | required | Tracking suffix appended to every final URL on this channel. Format: key=value pairs separated by `&`. Allowed characters: A–Z a–z 0–9 . _ ~ = & { } - or %XX percent-encoded. Pass empty string "" to clear. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/set_search_channel_final_url_suffix) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `campaign_id` | integer | required | The unique identifier of the wizard campaign. |
| `channel` | string | required | Which search channel on the campaign to update. Geo targeting is set per channel and only these two carry it.one of: `GOOGLE_ADS`, `MICROSOFT_ADS` |
| `countries` | array |   | Country NAMES to target, e.g. ["United States", "Canada"]. REPLACES the channel's current countries. Pass [] to clear (targets all locations). Omit to leave unchanged. |
| `states` | array |   | US state NAMES to target, e.g. ["Texas", "California"]. REPLACES the channel's current states. Pass [] to clear. Omit to leave unchanged. US states only. |
| `excluded_countries` | array |   | Country NAMES the campaign must NOT serve in, e.g. ["India"]. REPLACES the channel's current exclusions. Pass [] to clear them all. Omit to leave unchanged. Country-level only — states cannot be excluded. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/set_search_channel_locations) · [machine index](https://metadata.io/developers/tools.json)

## Analytics and attribution 16

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `startDate` | string | required | Start date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: '2025-01-01T00:00:00.000Z' |
| `endDate` | string | required | End date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: '2025-12-31T23:59:59.999Z' |
| `reportTab` | string | required | Funnel stage to analyze. Options: REACHED (default), ENGAGED, CONVERTED, MQL, OPPS, WONone of: `REACHED`, `ENGAGED`, `CONVERTED`, `MQL`, `OPPS`, `WON` |
| `page` | integer |   | Page number for pagination (0-based) |
| `size` | integer |   | Number of results per page. Default: 15, Max: 10000 — raise it to pull the full funnel set in one call. |
| `sort` | string |   | Sort criteria. Examples: 'impressions,desc' (default), 'engagement,desc', 'conversions,desc' |
| `type` | string |   | Report type. Currently only SOCIAL is supportedone of: `SOCIAL` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/account_funnel_reports) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `timeframe` | string |   | Timeframe for data aggregation. MONTH=monthly breakdown, QUARTER=quarterly breakdown, WEEK=weekly breakdown, YEAR=yearly breakdown. DO NOT use this parameter when providing startDate and endDate.one of: `QUARTER`, `WEEK`, `YEAR` |
| `startDate` | string |   | Start date for custom date range in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Must be used together with endDate. Do NOT provide timeframe when using this. Example: 2025-07-01T00:00:00.000Z |
| `endDate` | string |   | End date for custom date range in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Must be used together with startDate. Do NOT provide timeframe when using this. Example: 2025-09-30T00:00:00.000Z |

[Full page, schema and recorded response](https://metadata.io/developers/tools/account_level_stats) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `page` | integer |   | Page number for pagination (0-based). Example: page=0 for the first page. |
| `size` | integer |   | Number of results per page. Default: 25; raise it (up to 10000) to pull every account list in one call. |
| `sort` | string |   | Sorting criteria. Examples: 'triggeredAmount,desc', 'engagedAccounts,desc', 'influencedAmount,desc'. Format: field,direction where direction is 'asc' or 'desc'. |
| `channels` | string |   | Comma-separated channel names (e.g., 'LINKEDIN,FACEBOOK,INSTAGRAM,GOOGLE_ADS'). Leave empty for all channels. |
| `startDate` | string |   | Start date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: 2025-01-01T00:00:00.000Z. Optional for custom date ranges. |
| `endDate` | string |   | End date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: 2025-01-31T23:59:59.999Z. Optional for custom date ranges. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/account_list_performance) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `budget_group_name` | string | required | Name of the budget group to analyze (required). The tool will automatically look up the budget group ID. Example: 'Brand Awareness', 'ToFu', 'Lead Gen Q4' |
| `startDate` | string |   | Start date for analysis in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ, e.g., '2025-01-01T00:00:00.000Z'). Optional - if not provided, no start date filter is applied. |
| `endDate` | string |   | End date for analysis in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.SSSZ, e.g., '2025-12-15T23:59:59.999Z'). Optional - if not provided, no end date filter is applied. |
| `excludeExperimentName` | string |   | Experiment name to exclude from results. Useful for filtering out specific experiments from the analysis. |
| `page` | integer |   | Page number for pagination (0-based). Use for paginating through large result sets. |
| `size` | integer |   | Number of experiments per page. Default is 10. Use larger values (up to 10000) for comprehensive analysis — pull the whole set rather than a sample. |
| `sort` | string |   | Sort criteria for experiments. Format: field,field,direction. Examples: 'experimentId,name,asc', 'spent,desc', 'cpl,asc' |

[Full page, schema and recorded response](https://metadata.io/developers/tools/budget_group_performance) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `funnel_id` | integer | required | The funnel ID to analyze. Example: 35 |
| `startDate` | string |   | Start date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: '2025-01-01T00:00:00.000Z' |
| `endDate` | string |   | End date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: '2025-12-31T23:59:59.999Z' |
| `opportunityModel` | string |   | Opportunity attribution model. Options: ALL (default), TRIGGERED, INFLUENCEDone of: `ALL`, `TRIGGERED`, `INFLUENCED` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/deep_funnel_stats) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `fromMonth` | string |   | Start date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: 2025-01-01T00:00:00.000Z. Required for custom date ranges. |
| `toMonth` | string |   | End date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). Example: 2025-01-31T23:59:59.999Z. Required for custom date ranges. |
| `channels` | string |   | Comma-separated channel names (e.g., 'LINKEDIN,FACEBOOK,INSTAGRAM,GOOGLE_ADS'). Leave empty for all channels. |
| `page` | integer |   | Page number for pagination (0-based). Example: page=0 for the first page. |
| `size` | integer |   | Number of results per page. Default: 250; raise it (up to 10000) to pull every country in one call. |
| `sort` | string |   | Sorting criteria. Examples: 'spend,desc' (default), 'leads,desc', 'cpl,asc', 'impressions,desc'. Format: field,direction where direction is 'asc' or 'desc'. |
| `groupType` | string |   | Grouping type - currently only COUNTRY is supported for geographic breakdown.one of: `COUNTRY` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/demographic_country_stats) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `metrics` | array |   | List of metrics for secondary ordering when question involves multiple metrics (e.g., ['cpl', 'ctr', 'leads']). Only include when analyzing more than one metric simultaneously. Do NOT include for single metric questions. |
| `minSpend` | number |   | Minimum spend threshold. REQUIRED for all campaigns except Brand Awareness. Use for Lead Generation and when campaign type is unspecified. |
| `minLeads` | integer |   | Minimum leads threshold. REQUIRED for Lead Generation campaigns. Do NOT use for Brand Awareness campaigns. |
| `minCpl` | integer |   | Minimum cost per lead threshold (whole dollars). REQUIRED for Lead Generation campaigns. Do NOT use for Brand Awareness campaigns. |
| `minAudienceSize` | integer |   | Minimum audience size to filter experiments |
| `minClicks` | integer |   | Minimum clicks threshold. REQUIRED for Brand Awareness campaigns only. Do NOT use for Lead Generation campaigns. |
| `minCpc` | integer |   | Minimum cost per click threshold (whole dollars). Do NOT use for Lead Generation or unspecified campaign types. |
| `size` | integer |   | Number of results to return. RULES: size=1 for 'top' singular questions, size=requested number for 'top X' questions, size=50 for plural questions (e.g. 'campaigns'), size=30+ for multiple metrics analysis, size=15 as default when not specified. Raise it freely for full-dataset analytics — there is |
| `sort` | string |   | Sorting parameter. CRITICAL RULES: 'cpl2Score,desc' for Lead Generation or unspecified campaigns, 'cpc2Score,desc' for Brand Awareness, 'triggeredAmount,desc' for ROI/pipeline questions, 'oppsAmount,desc' for influenced pipeline, 'conversionRate,desc' for conversion rate, 'internalStatus,desc' for a |
| `goals` | string |   | Campaign goal type. RULES: 'CPL' for Lead Generation campaigns, 'CTR' for Brand Awareness campaigns. Do NOT include for unspecified campaign types. When multiple metrics involved, use only the first metric's corresponding goal.one of: `CPL`, `CTR` |
| `name` | object |   | Experiment name filter, matched as ONE substring per request. Use 'name' field (NOT experimentName) for specific experiment questions. Can be a single string or an array of strings for multiple experiments; an array is queried one name per request and the results are merged. Do NOT add additional pa |
| `campaignName` | object |   | Campaign name filter. Use when question is about specific campaign(s). Can be single string or array ['campaign1', 'campaign2'] for multiple campaigns. Do NOT include additional parameters when filtering by specific campaign name. |
| `audienceName` | string |   | Filter by target audience name (e.g., 'WTS EMEA Jan25_EMEAPitchbook') |
| `offerName` | string |   | Filter by specific offer name (e.g., 'AMER_ZO_EN_HBR Reimagining Work'). Use this field when question mentions specific offers. |
| `adName` | string |   | Filter by specific ad name (e.g., 'Sifted_WorkShift_Ad5_Beige'). Use 'adName' field when question asks about specific ad names. |
| `audienceTypes` | string |   | Comma-separated list of audience types (e.g., 'Spotlight Retargeting Contacts (Dynamic),Technographic (Aberdeen)') |
| `imageLibraryName` | string |   | Filter by creative/image name (e.g., 'JP - Square-Ad15.png'). Use 'imageLibraryName' field when question asks about specific creative names. |
| `offerTypes` | array |   | Offer types filter. RULES: ['LP'] for lead gen forms/landing pages questions, ['LP', 'LG'] as default when offer types mentioned. LP=Landing Pages, LG=Lead Gen forms. Should NOT be empty when included. |
| `channels` | array |   | Marketing channels to include |
| `visibilities` | array |   | Visibility status filter |
| `launchedExperimentStatuses` | array |   | Filter experiments by launch status. DEFAULT when omitted: successfully-launched experiments only (Active, WithoutSpend, Paused, Completed) — Failed and Disconnected are EXCLUDED, because a failed/non-launched experiment has 0 leads and is a non-starter, not a 'bottom performer'. Pass values explici |
| `timeFrame` | string |   | Timeframe aggregation. CRITICAL RULES: Use ONLY for WEEK or QUARTER questions. NEVER use 'YEAR' - use startDate/endDate instead. If timeFrame is included, DO NOT add startDate or endDate parameters under any circumstances.one of: `WEEK`, `QUARTER` |
| `startDate` | string |   | Start date in ISO 8601 format (e.g., '2024-10-18T00:00:00.000Z'). CRITICAL: Do NOT include if timeFrame parameter is used. Use last year of data if period cannot be inferred from question. For specific campaigns/experiments without timeframe, omit this parameter. |
| `endDate` | string |   | End date in ISO 8601 format. Must end on last hour of date (e.g., '2024-11-21T23:59:59.999Z'). CRITICAL: Do NOT include if timeFrame parameter is used. For specific campaigns/experiments without timeframe, omit this parameter. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/experiment_performance_stats) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domains` | array | required | Domain strings. E.g., ['metadata.io'] |
| `status` | array |   | Filter by status. Omit for all. |
| `startDate` | string |   | ISO 8601 format. E.g., '2025-01-01T00:00:00.000Z' |
| `endDate` | string |   | ISO 8601 format. |
| `page` | integer |   | 0-based page number. |
| `size` | integer |   | Items per page (default 25, max 10000). Raise it to pull the full set in one call. |
| `sort` | string |   | Sort field. Default: lastTouchDateone of: `lastTouchDate`, `status`, `name`, `amount` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_account_opportunities_insights) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domains` | array | required | Domain strings. E.g., ['metadata.io'] |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_account_summary_insights) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `statuses` | array |   | Lead statuses to include. The platform Leads tab defaults to ACTIVE. Omit to include all. |
| `campaignName` | string |   | Filter by campaign name (partial match). |
| `experimentName` | string |   | Filter by experiment name (partial match). |
| `customAudienceName` | string |   | Filter by targeted audience name (partial match). |
| `adName` | string |   | Filter by the ad (library) name that captured the leads (partial match). |
| `offerName` | string |   | Filter by the offer name tied to the leads' experiments. |
| `jobTitle` | string |   | Filter by lead job title (partial match). |
| `email` | string |   | Filter by lead email (partial match). |
| `firstName` | string |   | Filter by lead first name (partial match). |
| `lastName` | string |   | Filter by lead last name (partial match). |
| `businessEmails` | array |   | Filter by exact business email addresses (OR within the list). |
| `modifiedBy` | string |   | Filter by the platform user email who last modified the leads (partial match). |
| `companies` | array |   | Filter by exact company names. |
| `countries` | array |   | Filter by exact lead country names. |
| `channels` | array |   | Filter by acquisition channel(s). |
| `audienceTypes` | array |   | Filter by audience type of the leads' experiments (e.g. FIRMOGRAPHIC_INCLUDE, CONTACT_LIST, BUYER_INTENT, NATIVE_LINKEDIN). |
| `contentTypes` | array |   | Data-completeness filter: only leads that HAVE this content. |
| `qualityTypes` | array |   | Quality-signal filter (opportunities, MQL date/score). |
| `keyword` | string |   | Filter by the exact search keyword that captured the leads. |
| `matchTypes` | array |   | Filter by keyword match type (search channels). |
| `startDate` | string |   | Leads created on/after this date. ISO 8601; date-only is accepted. |
| `endDate` | string |   | Leads created on/before this date. ISO 8601; date-only is accepted. |
| `isFullyEnriched` | boolean |   | true = only fully enriched leads; false = only not fully enriched. |
| `isAutoUpdated` | boolean |   | true = only auto-enriched leads. |
| `isManuallyUpdate` | boolean |   | true = only manually enriched/edited leads (platform parameter name is 'isManuallyUpdate'). |
| `syncMA` | boolean |   | true = only leads synced to marketing automation; false = only unsynced. |
| `ids` | array |   | Restrict the summary to specific lead IDs. |
| `tagIds` | array |   | Filter by tag IDs on the leads' experiments. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_converted_leads_summary) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `accountName` | string |   | Filter by account/company name. |
| `startDate` | string\|null |   | ISO 8601 format or null. E.g., '2025-01-01T00:00:00.000Z' |
| `endDate` | string\|null |   | ISO 8601 format or null. |
| `criteria` | object\|null |   | Criteria object: {"operator":"AND","match":[{field,operator,type,value}]}. Use get_segment_criteria for saved segments. |
| `page` | integer |   | 0-based page number. |
| `sort` | string |   | Sort format: field,direction. Default: lastTouchDate,descone of: `timeInJourney,desc`, `timeInJourney,asc`, `revenue,desc`, `revenue,asc`, `oppCreatedAmount,desc`, `oppCreatedAmount,asc`, `highIntentDetails,desc`, `highIntentDetails,asc`, `engagementScoreClassificationDelta,desc`, `engagementScoreClassificationDelta,asc`, `engagementScoreClassification,desc`, `engagementScoreClassification,asc` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_insights_report) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `launchedExperimentStatuses` | array |   | Filter Performance Metrics by experiment launch statuses only. |
| `page` | integer |   | Page number to retrieve (0-based indexing) |
| `size` | integer |   | Number of results per page. Default 100; raise it freely (up to 10000) for comprehensive full-dataset analysis. |
| `sort` | string |   | Sorting criteria (e.g., 'spent,desc', 'cpl,asc', 'experimentId,spent,desc') |
| `ids` | array |   | Set of IDs to filter by |
| `experimentIds` | array |   | Set of experiment IDs to filter by |
| `startDate` | string |   | startDate in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ), e.g., `startDate=2025-06-12T14:30:00.123Z`). |
| `endDate` | string |   | endDate in ISO 8601 format (YYYY-MM-DDThh:mm:ssZ), e.g., `startDate=2025-06-12T14:30:00.123Z`). |
| `oppsStartDate` | string |   | Start date for opportunities data in ISO 8601 format |
| `oppsEndDate` | string |   | End date for opportunities data in ISO 8601 format |
| `adName` | string |   | Filter by specific ad name |
| `keyword` | string |   | Filter by specific keyword |
| `campaignName` | string |   | Filter by specific campaign name |
| `creativeName` | string |   | Filter by specific creative name |
| `customAudienceName` | string |   | Filter by specific custom audience name |
| `offerName` | string |   | Filter by specific offer name |
| `experimentName` | string |   | Filter by specific experiment name |
| `budgetGroupName` | string |   | Filter by specific budget group name |
| `channels` | array |   | Filter by marketing channels |
| `goals` | array |   | Filter by campaign goals |
| `audienceTypes` | array |   | Filter by audience types |
| `offerTypes` | array |   | Filter by offer types. LG=Lead Gen forms, LP=Landing Pages |
| `visibilities` | array |   | Filter by visibility status |
| `adFormats` | array |   | Filter by ad format types. Applied to ads endpoint automatically. |
| `minSpend` | number |   | Minimum spend threshold |
| `maxSpend` | number |   | Maximum spend threshold |
| `minLeads` | integer |   | Minimum number of leads threshold |
| `maxLeads` | integer |   | Maximum number of leads threshold |
| `minCpl` | number |   | Minimum cost per lead threshold |
| `maxCpl` | number |   | Maximum cost per lead threshold |
| `minAudienceSize` | integer |   | Minimum audience size threshold |
| `maxAudienceSize` | integer |   | Maximum audience size threshold |
| `usedInActiveExperiments` | boolean |   | Filter for ingredients used in active experiments only |
| `tags` | array |   | Set of tag IDs to filter by |
| `accountTagIds` | array |   | Set of account tag IDs to filter by |
| `showWithSpend` | boolean |   | Show only experiments/ingredients with spend data |
| `experimentList` | string |   | Experiment list filter |
| `customFieldIds` | string |   | Custom field IDs to include |
| `skipCustomFields` | boolean |   | Skip custom fields in response |
| `endpoint` | string |   | Specific endpoint to query. If not specified, will be auto-determined from query context. Use 'customAudience/group' for target groups.one of: `ads`, `customAudience`, `customAudience/group`, `offer`, `creative`, `keywords` |

[Full page, schema and recorded response](https://metadata.io/developers/tools/performance_metrics) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `question` | string | required | Natural-language question about the caller's account. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/query_metadata_analytics_account) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `question` | string | required | Natural-language question. Should describe a COHORT (industry × size × channel × format / audience), not a specific company. |
| `conversation_id` | any |   | Optional. Pass the value returned from a prior `_benchmarks` call to keep the query context warm. The two knowledge-base tools never share conversation_ids — pass only IDs returned by `_benchmarks` here. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/query_metadata_analytics_benchmarks) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `search_keywords` | array | required | Keywords to search for fields (3-10 recommended). E.g., ['page', 'url', 'visit'] |

[Full page, schema and recorded response](https://metadata.io/developers/tools/search_insights_criteria_fields) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `dateRange` | string | required | Timeframe for engagement data. Options: YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_MONTH, MONTH_TO_DATE (default), LIFETIME. REQUIRED parameter.one of: `YESTERDAY`, `LAST_7_DAYS`, `LAST_14_DAYS`, `LAST_30_DAYS`, `LAST_MONTH`, `MONTH_TO_DATE`, `LIFETIME` |
| `page` | integer |   | Page number for pagination (0-based). Example: page=0 for the first page. |
| `size` | integer |   | Number of results per page. Default: 15; raise it (up to 10000) to pull the full engagement set in one call. |
| `sort` | string |   | Sorting criteria. Examples: 'sessions,desc' (default), 'pageViews,desc', 'uniqueVisitors,desc', 'conversionRate,desc'. Format: field,direction where direction is 'asc' or 'desc'. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/website_engagement_stats) · [machine index](https://metadata.io/developers/tools.json)

## Account and access 10

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `crm` | string | required | The CRM system to connect. Must be one of: salesforce, hubspotone of: `salesforce`, `hubspot` |
| `acknowledge_data_access` | boolean |   | Set true to confirm the person you are acting for asked to connect this CRM. The response is an OAuth authorization URL that starts a credential grant into their Metadata account. Without this the call is refused. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/connect_crm) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

Takes no arguments.

[Full page, schema and recorded response](https://metadata.io/developers/tools/create_topup_link) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

Takes no arguments.

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_account_details) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

Takes no arguments.

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_credit_balance) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `page` | integer |   | Zero-based page number. Defaults to 0 (most recent). |
| `size` | integer |   | Rows per page, 1-100. Defaults to 25. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_credit_transactions) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `platformName` | string |   | Filter by specific platform name (e.g., 'Facebook', 'LinkedIn', 'Salesforce', 'HubSpot') |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_integrations_status) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `reference_id` | string | required | The payment's reference, as reported when the purchase was made (e.g. 'maxio:txn:987654'). Found on the transaction row in get_credit_transactions. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_payment_status) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `account_id` | string | required | ID of the Metadata account to switch into. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/impersonate_account) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `name` | string |   | Partial account name to search for. Optional for regular users (acts as a filter); required for super users (acts as the search query against the whole platform). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/list_user_accounts) · [machine index](https://metadata.io/developers/tools.json)

Creates or changes something in the account.

Takes no arguments.

[Full page, schema and recorded response](https://metadata.io/developers/tools/stop_impersonation) · [machine index](https://metadata.io/developers/tools.json)

## Utilities 5

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domain` | string | required | Company domain, e.g. 'metadata.io'. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/enrich_company_domain) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `domain` | string | required | Company website URL or domain. Examples: 'metadata.io', 'www.bloomreach.com', 'https://example.com' |

[Full page, schema and recorded response](https://metadata.io/developers/tools/find_privacy_url) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

Takes no arguments.

[Full page, schema and recorded response](https://metadata.io/developers/tools/get_current_date) · [machine index](https://metadata.io/developers/tools.json)

Returns data. Safe to call freely.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `ip` | string | required | The visitor's IP address (IPv4 or IPv6). |

[Full page, schema and recorded response](https://metadata.io/developers/tools/resolve_visitor_ip) · [machine index](https://metadata.io/developers/tools.json)

Deletes, archives, launches or moves budget. Confirm intent before calling.

| Parameter | Type |   | Notes |
|---|---|---|---|
| `subdomain` | string | required | The subdomain label only, without any zone suffix or scheme ("zoom", not "zoom.ad.live"). Empty string releases the current claim. |

[Full page, schema and recorded response](https://metadata.io/developers/tools/set_landing_subdomain) · [machine index](https://metadata.io/developers/tools.json)

## Machine-readable

Agents should read [/developers/tools.json](https://metadata.io/developers/tools.json) rather than this page: same 160 tools, full JSON Schema for every argument, one request.