> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinterest Ads

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

![Pinterest Ads logo](https://mintcdn.com/composio-preview/HvfZXDijhFOaKyF5/images/toolkits/pinterest_ads.svg?fit=max\&auto=format\&n=HvfZXDijhFOaKyF5\&q=85\&s=24057206e84b004a3b8357eeb3a38678)

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

## Tools

> [accordion] 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
>
> **columns** `array` *required*
>
> Supported Pinterest metrics and identifiers to return. MICRO\_DOLLAR values are advertiser-currency microunits.
>
> **end\_date** `string` *required*
>
> UTC report end date; must be on or after start\_date and at most 90 days after it.
>
> **entity\_ids** `array`
>
> 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` *required*
>
> 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")` *required*
>
> 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")` *required*
>
> Reporting level. Entity IDs are required for CAMPAIGN, AD\_GROUP, and AD, and forbidden for AD\_ACCOUNT.
>
> **ad\_account\_id** `string` *required*
>
> Advertiser account whose performance data to read.
>
> **view\_window\_days** `integer ("0" | "1" | "7" | "14" | "30" | "60")`
>
> Pinterest Tag view-attribution window in days.
>
> **click\_window\_days** `integer ("0" | "1" | "7" | "14" | "30" | "60")`
>
> Pinterest Tag click-attribution window in days.
>
> **conversion\_report\_time** `string ("TIME_OF_AD_ACTION" | "TIME_OF_CONVERSION")`
>
> Attribute conversion rows to the ad interaction date or conversion date.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **date** `string` *required*
>
> UTC analytics report date to check, in YYYY-MM-DD format.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **ad\_account\_id** `string`
>
> 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")` *required*
>
> Pinterest targeting dimension whose valid values to retrieve.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **page\_size** `integer`
>
> Maximum advertiser accounts in this page (1-250).
>
> **next\_cursor** `string`
>
> Continuation cursor returned by a previous call. Omit for the first page.
>
> **include\_shared\_accounts** `boolean`
>
> Include ad accounts shared with the connected user through Business Access.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **order** `string ("ASCENDING" | "DESCENDING")`
>
> Sort by ad-group ID; higher IDs are newer.
>
> **page\_size** `integer`
>
> Maximum ad groups in this page (1-250).
>
> **next\_cursor** `string`
>
> Continuation cursor returned by a previous call. Repeat the same filters when continuing.
>
> **ad\_group\_ids** `array`
>
> Optional ad-group IDs to look up. Pinterest marks this filter beta, so availability may vary by advertiser.
>
> **campaign\_ids** `array`
>
> Optional parent campaign IDs used to filter ad groups.
>
> **ad\_account\_id** `string` *required*
>
> Advertiser account ID returned by LIST\_AD\_ACCOUNTS.
>
> **entity\_statuses** `array`
>
> Statuses to include. If omitted, Pinterest returns only ACTIVE and PAUSED ad groups.
>
> **translate\_interests\_to\_names** `boolean`
>
> Return interest targeting as readable names instead of topic IDs.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **order** `string ("ASCENDING" | "DESCENDING")`
>
> Sort by ad ID. Higher IDs are associated with more recently added ads.
>
> **ad\_ids** `array`
>
> 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`
>
> Maximum ads in this page (1-250).
>
> **next\_cursor** `string`
>
> Continuation cursor returned by a previous call. Repeat the same filters when continuing.
>
> **ad\_group\_ids** `array`
>
> 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`
>
> Optional parent campaign IDs used to filter ads. Cannot be combined with ad\_group\_ids or ad\_ids.
>
> **ad\_account\_id** `string` *required*
>
> Advertiser account ID returned by LIST\_AD\_ACCOUNTS.
>
> **entity\_statuses** `array`
>
> Statuses to include. If omitted, Pinterest returns only ACTIVE and PAUSED ads.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **order** `string ("ASCENDING" | "DESCENDING")`
>
> Sort by campaign ID; higher IDs are newer.
>
> **page\_size** `integer`
>
> Maximum campaigns in this page (1-250).
>
> **next\_cursor** `string`
>
> Continuation cursor returned by a previous call. Repeat the same filters when continuing.
>
> **campaign\_ids** `array`
>
> Optional campaign IDs to look up; omit to list campaigns.
>
> **ad\_account\_id** `string` *required*
>
> Advertiser account ID returned by LIST\_AD\_ACCOUNTS.
>
> **entity\_statuses** `array`
>
> Statuses to include. If omitted Pinterest returns only ACTIVE and PAUSED campaigns.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **updates** `array` *required*
>
> 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` *required*
>
> Advertiser account that owns every ad group being updated.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **updates** `array` *required*
>
> 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` *required*
>
> Advertiser account that owns every ad being updated.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not

> [accordion] 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
>
> **updates** `array` *required*
>
> 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` *required*
>
> Advertiser account that owns every campaign being updated.
>
> #### Output
>
> **data** `string` *required*
>
> Data from the action execution
>
> **error** `string`
>
> Error if any occurred during the execution of the action
>
> **successful** `boolean` *required*
>
> Whether or not the action execution was successful or not
