Skip to main content
Pinterest Ads logo
  • Category: ads & conversion
  • Auth: OAUTH2
  • Composio-managed OAuth available? Yes
  • Tools: 10
  • Triggers: 0
  • Slug: PINTEREST_ADS
  • Version: 20261030_00

Tools

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

Input Parameters

array
required
Supported Pinterest metrics and identifiers to return. MICRO_DOLLAR values are advertiser-currency microunits.
string
required
UTC report end date; must be on or after start_date and at most 90 days after it.
array
Campaign, ad-group, or ad IDs for the chosen entity_level. Required unless entity_level is AD_ACCOUNT; forbidden for AD_ACCOUNT.
string
required
UTC report start date. It may be at most 90 days before today, or 8 days before today when granularity is HOUR.
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.
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.
string
required
Advertiser account whose performance data to read.
integer ("0" | "1" | "7" | "14" | "30" | "60")
Pinterest Tag view-attribution window in days.
integer ("0" | "1" | "7" | "14" | "30" | "60")
Pinterest Tag click-attribution window in days.
string ("TIME_OF_AD_ACTION" | "TIME_OF_CONVERSION")
Attribute conversion rows to the ad interaction date or conversion date.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_GET_METRICS_READY_STATECheck whether Pinterest conversion and non-conversion metrics are finalized for a UTC report date before relying on analytics results.

Input Parameters

string
required
UTC analytics report date to check, in YYYY-MM-DD format.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_GET_TARGETING_OPTIONSGet Pinterest’s valid targeting values for a targeting type, such as age buckets, gender, locale, location, interests, or keywords.

Input Parameters

string
Optional advertiser account context. Omit to retrieve options for the connected Pinterest user.
string ("APPTYPE" | "GENDER" | "LOCALE" | "AGE_BUCKET" | "LOCATION" | "GEO" | "INTEREST" | "KEYWORD" | "AUDIENCE_INCLUDE" | "AUDIENCE_EXCLUDE")
required
Pinterest targeting dimension whose valid values to retrieve.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_LIST_AD_ACCOUNTSList advertiser accounts the connected Pinterest user owns or can access, including the IDs needed by all other Ads tools.

Input Parameters

integer
Maximum advertiser accounts in this page (1-250).
string
Continuation cursor returned by a previous call. Omit for the first page.
boolean
Include ad accounts shared with the connected user through Business Access.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_LIST_AD_GROUPSList ad groups for an advertiser, filter by parent campaigns, or look up specific ad groups by ID.

Input Parameters

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_LIST_ADSList 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

string ("ASCENDING" | "DESCENDING")
Sort by ad ID. Higher IDs are associated with more recently added ads.
array
Optional ad IDs to look up. Cannot be combined with campaign_ids or ad_group_ids; omit all ID filters to list ads.
integer
Maximum ads in this page (1-250).
string
Continuation cursor returned by a previous call. Repeat the same filters when continuing.
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.
array
Optional parent campaign IDs used to filter ads. Cannot be combined with ad_group_ids or ad_ids.
string
required
Advertiser account ID returned by LIST_AD_ACCOUNTS.
array
Statuses to include. If omitted, Pinterest returns only ACTIVE and PAUSED ads.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_LIST_CAMPAIGNSList 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

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

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_UPDATE_AD_GROUPSRename, 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

array
required
One to 30 ad-group changes. IDs must be unique; each item must set a new name, ACTIVE status, or PAUSED status.
string
required
Advertiser account that owns every ad group being updated.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_UPDATE_ADSRename, 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

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.
string
required
Advertiser account that owns every ad being updated.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not
Slug: PINTEREST_ADS_UPDATE_CAMPAIGNSRename, 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

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.
string
required
Advertiser account that owns every campaign being updated.

Output

string
required
Data from the action execution
string
Error if any occurred during the execution of the action
boolean
required
Whether or not the action execution was successful or not