Pinterest
P
Pinterest

tap-pinterest (meltanolabs variant)

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.

FieldDescription
idUnique identifier of the ad account
nameDisplay name of the ad account
countryCountry code of the ad account
currencyCurrency used by the ad account
ownerOwner user object (id, username)
permissionsList of permission levels granted to the current user
created_timeTimestamp when the account was created
updated_timeTimestamp when the account was last updated

campaigns

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

FieldDescription
idUnique identifier of the campaign
ad_account_idID of the parent ad account
nameCampaign name
statusCampaign status (ACTIVE, PAUSED, ARCHIVED, etc.)
objective_typeCampaign objective (AWARENESS, CONSIDERATION, CONVERSION, etc.)
typeCampaign type
start_timeScheduled start timestamp
end_timeScheduled end timestamp
daily_spend_capDaily budget cap in micro-currency
lifetime_spend_capLifetime budget cap in micro-currency
is_campaign_budget_optimizationWhether campaign budget optimisation is enabled
is_flexible_daily_budgetsWhether flexible daily budgets are enabled
is_automated_campaignWhether automated campaign features are enabled
is_performance_plusWhether Performance+ features are enabled
tracking_urlsClick and impression tracking URLs
bid_optionsBid strategy options
order_line_idAssociated order line ID
summary_statusHigh-level status summary
created_timeTimestamp when the campaign was created
updated_timeTimestamp when the campaign was last updated

ad_groups

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

FieldDescription
idUnique identifier of the ad group
nameAd group name
ad_account_idID of the parent ad account
campaign_idID of the parent campaign
statusAd group status
budget_in_micro_currencyBudget in micro-currency (divide by 1,000,000 for actual value)
bid_in_micro_currencyBid amount in micro-currency
bid_strategy_typeBid strategy type
bid_multiplierBid multiplier
budget_typeType of budget (DAILY, LIFETIME, etc.)
billable_eventThe billable event type
start_timeAd group start timestamp
end_timeAd group end timestamp
placement_groupPlacement group (ALL_PLACEMENTS, etc.)
pacing_delivery_typePacing and delivery type
targeting_specAudience targeting specification object
targeting_template_idsIDs of targeting templates applied
optimization_goal_metadataGoal metadata for bid optimisation
lifetime_frequency_capLifetime frequency cap
tracking_urlsTracking URLs
auto_targeting_enabledWhether auto-targeting is enabled
is_creative_optimizationWhether creative optimisation is enabled
conversion_learning_mode_typeConversion learning mode type
promotion_idPromotion ID if applicable
promotion_application_levelLevel at which the promotion is applied
feed_profile_idFeed profile ID
summary_statusHigh-level status summary
typeAd group type
created_timeTimestamp when the ad group was created
updated_timeTimestamp when the ad group was last updated

ads

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

FieldDescription
idUnique identifier of the ad
nameAd name
ad_account_idID of the parent ad account
campaign_idID of the parent campaign
ad_group_idID of the parent ad group
pin_idID of the Pin used as the creative
statusAd status (ACTIVE, PAUSED, ARCHIVED, etc.)
creative_typeCreative type (REGULAR, VIDEO, SHOPPING, CAROUSEL, etc.)
destination_urlLanding page URL
android_deep_linkDeep link URL for Android
ios_deep_linkDeep link URL for iOS
click_tracking_urlClick tracking URL
view_tracking_urlView/impression tracking URL
disclosure_typeDisclosure type for branded content
disclosure_urlDisclosure URL
lead_form_idID of the attached lead form
grid_click_typeGrid click type for collection ads
customizable_cta_typeCall-to-action button type
is_pin_deletedWhether the source Pin has been deleted
is_removableWhether the ad can be removed
review_statusCurrent ad review status
rejected_reasonsList of rejection reasons
rejection_labelsLabels associated with any rejections
tracking_urlsTracking URLs
collection_items_destination_url_templateDestination URL template for collection items
carousel_destination_urlsDestination URLs for carousel slides
carousel_android_deep_linksAndroid deep links for carousel slides
carousel_ios_deep_linksiOS deep links for carousel slides
quiz_pin_dataQuiz pin configuration data
summary_statusHigh-level status summary
typeAd type
created_timeTimestamp when the ad was created
updated_timeTimestamp when the ad was last updated

pins

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

FieldDescription
idUnique identifier of the Pin
titlePin title
descriptionPin description
linkDestination URL
alt_textAlt text for the Pin image
board_idID of the board the Pin belongs to
board_section_idID of the board section
board_ownerOwner of the board (id, username)
creative_typeCreative type of the Pin
dominant_colorDominant hex colour of the Pin image
mediaMedia object (images, videos, etc.)
parent_pin_idID of the parent Pin if this is a derivative
pin_metricsOrganic engagement metrics snapshot
has_been_promotedWhether this Pin has ever been used as an ad
is_ownerWhether the authenticated user owns this Pin
is_standardWhether this is a standard Pin
created_atTimestamp 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.

FieldDescription
CAMPAIGN_IDID of the campaign
DATEDate of the metrics
metricsObject 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.

FieldDescription
AD_IDID of the ad
DATEDate of the metrics
metricsObject 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.

FieldDescription
pin_idID of the Pin
app_typeApplication type segment (e.g. TOTAL, MOBILE, WEB)
dateDate of the metrics
metricsObject 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.

Meltano Cloud Connector

Pinterest connector is available on Meltano. It is built, maintained, supported, and tested by Meltano.

Why Meltano Cloud?
Expert supportDirect access to the team that built and maintains Meltano Cloud. Same-day responses during UK business hours. When something breaks, we fix it fast because we know exactly how it works.
Rigorously testedEvery connector goes through comprehensive testing and quality checks before production. Daily monitoring catches issues before they hit your pipelines. We don't just wrap open-source taps and hope for the best. We validate, we test, we maintain.
No maintenance overheadAPI changes. Connector updates. Schema drift. Breaking changes from upstream sources. We handle it all. Your team focuses on using data. Our team focuses on making sure it's there when you need it.
Ingest & transform data with AIConnect Claude or any MCP-compatible assistant to Meltano Cloud. Add connectors, run pipelines, build dbt models and diagnose failed runs in plain English, against the same Git-backed project your team works in.
Access to Meltano Slack communityJoin 5,500+ data engineers and analytics practitioners. The community is active, helpful, and always on. Good for quick questions, sharing patterns, and learning what others are building.