---
canonical_url: "https://docs.composio.dev/toolkits/pinterest_ads"
markdown_url: "https://docs.composio.dev/toolkits/pinterest_ads.md"
product: "platform"
version: null
last_updated: null
---

# Pinterest Ads

Pinterest Ads API for managing advertising accounts, campaigns, ad groups, ads, targeting, and reporting.

- **Category:** ads & conversion
- **Auth:** OAUTH2
- **Composio-managed OAuth available?** Yes
- **Tools:** 10
- **Triggers:** 0
- **Slug:** `PINTEREST_ADS`
- **Version:** 20260826_00

## Tools

### Get Ads Analytics

**Slug:** `PINTEREST_ADS_GET_ANALYTICS`

Get synchronous Pinterest Ads performance metrics for an advertiser or selected campaigns, ad groups, or ads over a date range.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `columns` | array | Yes | Supported Pinterest metrics and identifiers to return. MICRO_DOLLAR values are advertiser-currency microunits. |
| `end_date` | string | Yes | UTC report end date; must be on or after start_date and at most 90 days after it. |
| `entity_ids` | array | No | Campaign, ad-group, or ad IDs for the chosen entity_level. Required unless entity_level is AD_ACCOUNT; forbidden for AD_ACCOUNT. |
| `start_date` | string | Yes | UTC report start date. It may be at most 90 days before today, or 8 days before today when granularity is HOUR. |
| `granularity` | string ("TOTAL" | "DAY" | "HOUR" | "WEEK" | "MONTH") | Yes | Time grouping for metric rows: TOTAL, DAY, HOUR, WEEK, or MONTH. HOUR no longer provides conversion metrics, is limited to the previous 8 days, and has a 3-day maximum range for campaign, ad-group, and ad reports. |
| `entity_level` | string ("AD_ACCOUNT" | "CAMPAIGN" | "AD_GROUP" | "AD") | Yes | Reporting level. Entity IDs are required for CAMPAIGN, AD_GROUP, and AD, and forbidden for AD_ACCOUNT. |
| `ad_account_id` | string | Yes | Advertiser account whose performance data to read. |
| `view_window_days` | integer ("0" | "1" | "7" | "14" | "30" | "60") | No | Pinterest Tag view-attribution window in days. |
| `click_window_days` | integer ("0" | "1" | "7" | "14" | "30" | "60") | No | Pinterest Tag click-attribution window in days. |
| `conversion_report_time` | string ("TIME_OF_AD_ACTION" | "TIME_OF_CONVERSION") | No | Attribute conversion rows to the ad interaction date or conversion date. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Metrics Ready State

**Slug:** `PINTEREST_ADS_GET_METRICS_READY_STATE`

Check whether Pinterest conversion and non-conversion metrics are finalized for a UTC report date before relying on analytics results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `date` | string | Yes | UTC analytics report date to check, in YYYY-MM-DD format. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Targeting Options

**Slug:** `PINTEREST_ADS_GET_TARGETING_OPTIONS`

Get Pinterest's valid targeting values for a targeting type, such as age buckets, gender, locale, location, interests, or keywords.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ad_account_id` | string | No | Optional advertiser account context. Omit to retrieve options for the connected Pinterest user. |
| `targeting_type` | string ("APPTYPE" | "GENDER" | "LOCALE" | "AGE_BUCKET" | "LOCATION" | "GEO" | "INTEREST" | "KEYWORD" | "AUDIENCE_INCLUDE" | "AUDIENCE_EXCLUDE") | Yes | Pinterest targeting dimension whose valid values to retrieve. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Ad Accounts

**Slug:** `PINTEREST_ADS_LIST_AD_ACCOUNTS`

List advertiser accounts the connected Pinterest user owns or can access, including the IDs needed by all other Ads tools.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page_size` | integer | No | Maximum advertiser accounts in this page (1-250). |
| `next_cursor` | string | No | Continuation cursor returned by a previous call. Omit for the first page. |
| `include_shared_accounts` | boolean | No | Include ad accounts shared with the connected user through Business Access. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Ad Groups

**Slug:** `PINTEREST_ADS_LIST_AD_GROUPS`

List ad groups for an advertiser, filter by parent campaigns, or look up specific ad groups by ID.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `order` | string ("ASCENDING" | "DESCENDING") | No | Sort by ad-group ID; higher IDs are newer. |
| `page_size` | integer | No | Maximum ad groups in this page (1-250). |
| `next_cursor` | string | No | Continuation cursor returned by a previous call. Repeat the same filters when continuing. |
| `ad_group_ids` | array | No | Optional ad-group IDs to look up. Pinterest marks this filter beta, so availability may vary by advertiser. |
| `campaign_ids` | array | No | Optional parent campaign IDs used to filter ad groups. |
| `ad_account_id` | string | Yes | Advertiser account ID returned by LIST_AD_ACCOUNTS. |
| `entity_statuses` | array | No | Statuses to include. If omitted, Pinterest returns only ACTIVE and PAUSED ad groups. |
| `translate_interests_to_names` | boolean | No | Return interest targeting as readable names instead of topic IDs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Ads

**Slug:** `PINTEREST_ADS_LIST_ADS`

List ads for an advertiser, filter by one hierarchy level, or look up specific ads by ID. Archived and draft ads must be requested explicitly with entity_statuses.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `order` | string ("ASCENDING" | "DESCENDING") | No | Sort by ad ID. Higher IDs are associated with more recently added ads. |
| `ad_ids` | array | No | Optional ad IDs to look up. Cannot be combined with campaign_ids or ad_group_ids; omit all ID filters to list ads. |
| `page_size` | integer | No | Maximum ads in this page (1-250). |
| `next_cursor` | string | No | Continuation cursor returned by a previous call. Repeat the same filters when continuing. |
| `ad_group_ids` | array | No | Optional parent ad-group IDs used to filter ads. This beta filter may not be available to every advertiser and cannot be combined with campaign_ids or ad_ids. |
| `campaign_ids` | array | No | Optional parent campaign IDs used to filter ads. Cannot be combined with ad_group_ids or ad_ids. |
| `ad_account_id` | string | Yes | Advertiser account ID returned by LIST_AD_ACCOUNTS. |
| `entity_statuses` | array | No | Statuses to include. If omitted, Pinterest returns only ACTIVE and PAUSED ads. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Campaigns

**Slug:** `PINTEREST_ADS_LIST_CAMPAIGNS`

List campaigns for an advertiser, or look up specific campaigns by ID using campaign_ids. Archived and draft campaigns must be requested explicitly with entity_statuses.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `order` | string ("ASCENDING" | "DESCENDING") | No | Sort by campaign ID; higher IDs are newer. |
| `page_size` | integer | No | Maximum campaigns in this page (1-250). |
| `next_cursor` | string | No | Continuation cursor returned by a previous call. Repeat the same filters when continuing. |
| `campaign_ids` | array | No | Optional campaign IDs to look up; omit to list campaigns. |
| `ad_account_id` | string | Yes | Advertiser account ID returned by LIST_AD_ACCOUNTS. |
| `entity_statuses` | array | No | Statuses to include. If omitted Pinterest returns only ACTIVE and PAUSED campaigns. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Ad Groups

**Slug:** `PINTEREST_ADS_UPDATE_AD_GROUPS`

Rename, pause, or resume up to 30 existing ad groups. Setting status to ACTIVE can restart delivery and incur spend under existing budgets. Budget, bid, targeting, schedule, and restricted-setting changes are not exposed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `updates` | array | Yes | One to 30 ad-group changes. IDs must be unique; each item must set a new name, ACTIVE status, or PAUSED status. |
| `ad_account_id` | string | Yes | Advertiser account that owns every ad group being updated. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Ads

**Slug:** `PINTEREST_ADS_UPDATE_ADS`

Rename, pause, or resume up to 30 existing Pinterest ads. Setting status to ACTIVE can restart delivery and incur spend under existing budgets. Creative, Pin, destination, tracking, and disclosure changes are not exposed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `updates` | array | Yes | One to 30 ad updates. IDs must be unique, and each item must set a name, an ACTIVE status, or a PAUSED status. |
| `ad_account_id` | string | Yes | Advertiser account that owns every ad being updated. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Campaigns

**Slug:** `PINTEREST_ADS_UPDATE_CAMPAIGNS`

Rename, pause, or resume up to 30 existing campaigns. Setting status to ACTIVE can restart delivery and incur spend under existing budgets. Budget, schedule, objective, archive, and restricted-setting changes are not exposed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `updates` | array | Yes | Campaign changes (1-30). Each item requires a unique campaign ID and at least one of non-empty name or ACTIVE/PAUSED status. |
| `ad_account_id` | string | Yes | Advertiser account that owns every campaign being updated. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |