Pinterest is a visual discovery platform where people find inspiration and ideas for their interests and projects.

Pinterest offers an API that allows businesses to access their advertising and analytics data, including campaigns, ad groups, ads, and performance metrics. The tap-pinterest extractor connects to the Pinterest API v5 to extract data about your Pinterest Ads account — including campaigns, ad groups, ads, pins, and detailed analytics.

Prerequisites

To connect to Pinterest, you need to authenticate using OAuth2. Use the Connect with Pinterest button to authenticate through the Matatika OAuth proxy. This handles token management automatically.

Available Streams

ad_accounts

All ad accounts accessible to the authenticated user. Campaigns, ad groups, ads, and analytics are fetched as child streams for each account.

| Field | Description | |---|---| | id | Unique identifier of the ad account | | name | Display name of the ad account | | country | Country code of the ad account | | currency | Currency used by the ad account | | owner | Owner user object (id, username) | | permissions | List of permission levels granted to the current user | | created_time | Timestamp when the account was created | | updated_time | Timestamp when the account was last updated |

campaigns

All campaigns within each ad account. Incrementally synced by updated_time.

| Field | Description | |---|---| | id | Unique identifier of the campaign | | ad_account_id | ID of the parent ad account | | name | Campaign name | | status | Campaign status (ACTIVE, PAUSED, ARCHIVED, etc.) | | objective_type | Campaign objective (AWARENESS, CONSIDERATION, CONVERSION, etc.) | | type | Campaign type | | start_time | Scheduled start timestamp | | end_time | Scheduled end timestamp | | daily_spend_cap | Daily budget cap in micro-currency | | lifetime_spend_cap | Lifetime budget cap in micro-currency | | is_campaign_budget_optimization | Whether campaign budget optimisation is enabled | | is_flexible_daily_budgets | Whether flexible daily budgets are enabled | | is_automated_campaign | Whether automated campaign features are enabled | | is_performance_plus | Whether Performance+ features are enabled | | tracking_urls | Click and impression tracking URLs | | bid_options | Bid strategy options | | order_line_id | Associated order line ID | | summary_status | High-level status summary | | created_time | Timestamp when the campaign was created | | updated_time | Timestamp when the campaign was last updated |

ad_groups

All ad groups within each ad account. Incrementally synced by updated_time.

| Field | Description | |---|---| | id | Unique identifier of the ad group | | name | Ad group name | | ad_account_id | ID of the parent ad account | | campaign_id | ID of the parent campaign | | status | Ad group status | | budget_in_micro_currency | Budget in micro-currency (divide by 1,000,000 for actual value) | | bid_in_micro_currency | Bid amount in micro-currency | | bid_strategy_type | Bid strategy type | | bid_multiplier | Bid multiplier | | budget_type | Type of budget (DAILY, LIFETIME, etc.) | | billable_event | The billable event type | | start_time | Ad group start timestamp | | end_time | Ad group end timestamp | | placement_group | Placement group (ALL_PLACEMENTS, etc.) | | pacing_delivery_type | Pacing and delivery type | | targeting_spec | Audience targeting specification object | | targeting_template_ids | IDs of targeting templates applied | | optimization_goal_metadata | Goal metadata for bid optimisation | | lifetime_frequency_cap | Lifetime frequency cap | | tracking_urls | Tracking URLs | | auto_targeting_enabled | Whether auto-targeting is enabled | | is_creative_optimization | Whether creative optimisation is enabled | | conversion_learning_mode_type | Conversion learning mode type | | promotion_id | Promotion ID if applicable | | promotion_application_level | Level at which the promotion is applied | | feed_profile_id | Feed profile ID | | summary_status | High-level status summary | | type | Ad group type | | created_time | Timestamp when the ad group was created | | updated_time | Timestamp when the ad group was last updated |

ads

All ads within each ad account. Incrementally synced by updated_time.

| Field | Description | |---|---| | id | Unique identifier of the ad | | name | Ad name | | ad_account_id | ID of the parent ad account | | campaign_id | ID of the parent campaign | | ad_group_id | ID of the parent ad group | | pin_id | ID of the Pin used as the creative | | status | Ad status (ACTIVE, PAUSED, ARCHIVED, etc.) | | creative_type | Creative type (REGULAR, VIDEO, SHOPPING, CAROUSEL, etc.) | | destination_url | Landing page URL | | android_deep_link | Deep link URL for Android | | ios_deep_link | Deep link URL for iOS | | click_tracking_url | Click tracking URL | | view_tracking_url | View/impression tracking URL | | disclosure_type | Disclosure type for branded content | | disclosure_url | Disclosure URL | | lead_form_id | ID of the attached lead form | | grid_click_type | Grid click type for collection ads | | customizable_cta_type | Call-to-action button type | | is_pin_deleted | Whether the source Pin has been deleted | | is_removable | Whether the ad can be removed | | review_status | Current ad review status | | rejected_reasons | List of rejection reasons | | rejection_labels | Labels associated with any rejections | | tracking_urls | Tracking URLs | | collection_items_destination_url_template | Destination URL template for collection items | | carousel_destination_urls | Destination URLs for carousel slides | | carousel_android_deep_links | Android deep links for carousel slides | | carousel_ios_deep_links | iOS deep links for carousel slides | | quiz_pin_data | Quiz pin configuration data | | summary_status | High-level status summary | | type | Ad type | | created_time | Timestamp when the ad was created | | updated_time | Timestamp when the ad was last updated |

pins

All pins created by the authenticated user. Incrementally synced by created_at.

| Field | Description | |---|---| | id | Unique identifier of the Pin | | title | Pin title | | description | Pin description | | link | Destination URL | | alt_text | Alt text for the Pin image | | board_id | ID of the board the Pin belongs to | | board_section_id | ID of the board section | | board_owner | Owner of the board (id, username) | | creative_type | Creative type of the Pin | | dominant_color | Dominant hex colour of the Pin image | | media | Media object (images, videos, etc.) | | parent_pin_id | ID of the parent Pin if this is a derivative | | pin_metrics | Organic engagement metrics snapshot | | has_been_promoted | Whether this Pin has ever been used as an ad | | is_owner | Whether the authenticated user owns this Pin | | is_standard | Whether this is a standard Pin | | created_at | Timestamp when the Pin was created |

campaign_analytics

Daily or aggregated performance metrics for each campaign, keyed by campaign and date. Requires a start_date. Pinterest limits analytics requests to a 90-day window.

| Field | Description | |---|---| | CAMPAIGN_ID | ID of the campaign | | DATE | Date of the metrics | | metrics | Object containing requested metric values (configured via Analytics Columns) |

Default metrics returned in the metrics object: SPEND_IN_DOLLAR, PAID_IMPRESSION, TOTAL_IMPRESSION, TOTAL_CLICKTHROUGH, TOTAL_ENGAGEMENT, CTR, ECTR, CPC_IN_MICRO_DOLLAR, ECPC_IN_DOLLAR, CAMPAIGN_ID, AD_GROUP_ID, AD_ID, PIN_ID, AD_ACCOUNT_ID, CAMPAIGN_NAME, AD_GROUP_NAME, AD_NAME.

ad_analytics

Daily or aggregated performance metrics for each individual ad, keyed by ad and date. Requires a start_date. Pinterest limits analytics requests to a 90-day window.

| Field | Description | |---|---| | AD_ID | ID of the ad | | DATE | Date of the metrics | | metrics | Object containing requested metric values (configured via Analytics Columns) |

pin_analytics

Daily organic engagement metrics per pin, broken down by app type (e.g. TOTAL, MOBILE, WEB). Requires a start_date.

| Field | Description | |---|---| | pin_id | ID of the Pin | | app_type | Application type segment (e.g. TOTAL, MOBILE, WEB) | | date | Date of the metrics | | metrics | Object containing metric values: IMPRESSION, OUTBOUND_CLICK, PIN_CLICK, SAVE, SAVE_RATE |

Settings

Start Date

Start date for analytics streams in YYYY-MM-DD format. Defaults to 30 days ago. Pinterest limits analytics to 90 days per request.

Analytics Columns

List of metric columns to fetch for analytics streams. Defaults to a standard set of spend, impression, click, and engagement metrics.

Analytics Granularity

Granularity for analytics streams. One of TOTAL, DAY, HOUR, WEEK, MONTH.