ContextQMD
Back to Airbyte

Pinterest

docs/integrations/sources/pinterest.md

2.0.061.8 KB
Original Source

Pinterest

This page contains the setup guide and reference information for the Pinterest source connector.

Prerequisites

<!-- env:cloud -->

When setting up the Pinterest source connector with Airbyte Cloud, be aware that Pinterest does not allow configuring permissions during the OAuth authentication process. Therefore, the following permissions will be requested during authentication:

  • See all of your advertising data, including ads, ad groups, campaigns, etc.
  • See your public boards, including group boards you join.
  • See your secret boards.
  • See all of your catalogs data.
  • See your public Pins.
  • See your secret Pins.
  • See your user accounts and followers.

For more information on the scopes required for Pinterest OAuth, please refer to the Pinterest API Scopes documentation.

<!-- /env:cloud --> <!-- env:oss -->

To set up the Pinterest source connector with Airbyte Open Source, you'll need your Pinterest App ID and secret key and the refresh token.

<!-- /env:oss -->

Different streams in this connector require different Pinterest OAuth scopes:

  • Account analytics (user_account_analytics): Requires user_accounts:read.
  • Boards, board sections, and board pins: Require boards:read and pins:read.
  • Ad accounts, campaigns, ad groups, ads, and their analytics: Require ads:read.
  • Catalogs, catalog feeds, and catalog product groups: Require catalogs:read.

If your Pinterest account has limited permissions, some streams may not return data. The connector validates your connection using the user_account_analytics stream, which requires only the user_accounts:read scope. This scope is available to all authenticated Pinterest users.

Setup guide

<!-- env:cloud -->

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Pinterest from the Source type dropdown.
  4. Enter the name for the Pinterest connector.
  5. The OAuth2.0 authorization method is selected by default. Click Authenticate your Pinterest account. Log in and authorize your Pinterest account.
  6. (Optional) For Start Date, enter the date in YYYY-MM-DD format. The connector replicates data on and after this date. If you don't set a date, the connector defaults to the maximum lookback period allowed by each stream. Analytics streams can look back up to 90 days. Report streams can look back up to 913 days.
  7. (Optional) Select one or multiple status values from the dropdown menu. For the ads, ad_groups, and campaigns streams, specifying a status will filter out records that do not match the specified ones. If a status is not specified, the source will default to records with a status of either ACTIVE or PAUSED.
  8. (Optional) Add custom reports if needed. For more information, refer to the corresponding section.
  9. (Optional) Enter an Ad Account ID. If specified, the source will only retrieve data for that specific Pinterest Ad Account.
  10. Click Set up source.
<!-- /env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

  1. Navigate to the Airbyte Open Source dashboard.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Pinterest from the Source type dropdown.
  4. Enter the name for the Pinterest connector.
  5. The OAuth2.0 authorization method is selected by default. For Client ID and Client Secret, enter your Pinterest App ID and secret key. For Refresh Token, enter your Pinterest Refresh Token.
  6. (Optional) For Start Date, enter the date in YYYY-MM-DD format. The connector replicates data on and after this date. If you don't set a date, the connector defaults to the maximum lookback period allowed by each stream. Analytics streams can look back up to 90 days. Report streams can look back up to 913 days.
  7. (Optional) Select one or multiple status values from the dropdown menu. For the ads, ad_groups, and campaigns streams, specifying a status will filter out records that do not match the specified ones. If a status is not specified, the source will default to records with a status of either ACTIVE or PAUSED.
  8. (Optional) Add custom reports if needed. For more information, refer to the corresponding section.
  9. (Optional) Enter an Ad Account ID. If specified, the source will only retrieve data for that specific Pinterest Ad Account.
  10. Click Set up source.
<!-- /env:oss -->

Supported sync modes

The Pinterest source connector supports the following sync modes:

Supported Streams

Custom reports

Custom reports in the Pinterest connector allow you to create personalized analytics reports for your account. You can tailor these reports to your specific needs by choosing from various properties:

  1. Name: A unique identifier for the report.
  2. Level: Specifies the data aggregation level, with options like ADVERTISER, CAMPAIGN, AD_GROUP, etc. The default level is ADVERTISER.
  3. Granularity: Determines the data granularity, such as TOTAL, DAY, HOUR, etc. The default is TOTAL, where metrics are aggregated over the specified date range.
  4. Columns: Identifies the data columns to be included in the report.
  5. Click Window Days (Optional): The number of days used for conversion attribution from a pin click action. This applies to Pinterest Tag conversion metrics. Valid values are 0, 1, 7, 14, 30, and 60. Defaults to 30 days if not specified. Set to 0 to disable click attribution.
  6. Engagement Window Days (Optional): The number of days used for conversion attribution from an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. This applies to Pinterest Tag conversion metrics. Valid values are 0, 1, 7, 14, 30, and 60. Defaults to 30 days if not specified. Set to 0 to disable engagement attribution.
  7. View Window Days (Optional): The number of days used as the conversion attribution window for a view action. This applies to Pinterest Tag conversion metrics. Valid values are 0, 1, 7, 14, 30, and 60. Defaults to 30 days if not specified. Set to 0 to disable view attribution.
  8. Conversion Report Time (Optional): Indicates the date by which the conversion metrics returned will be reported. There are two dates associated with a conversion event: the date of ad interaction and the date of conversion event completion. The default is TIME_OF_AD_ACTION.
  9. Attribution Types (Optional): Lists the types of attribution for the report, such as INDIVIDUAL or HOUSEHOLD.
  10. Start Date (Optional): The start date for the report in YYYY-MM-DD format, defaulting to the latest allowed date by the report API (913 days from today).

For more detailed information and guidelines on creating custom reports, please refer to the Pinterest API documentation.

Performance considerations

The connector is restricted by the Pinterest rate limits. The Pinterest API enforces rate limits per endpoint category. For example, analytics endpoints allow 300 requests per minute with standard access, while general read endpoints allow 1,000 requests per minute. For details, see the Pinterest rate limits documentation.

Changelog

<details> <summary>Expand to review</summary>
VersionDatePull RequestSubject
2.1.262026-03-1774453Update dependencies
2.1.252026-03-0974339Add TOTAL_IMPRESSION column to custom reports
2.1.242026-03-0974120Fix custom reports engagement_window_days and view_window_days default values from array [30] to integer 30; fix or 30 fallback to correctly handle 0 as a valid value
2.1.232026-02-2473845Update dependencies
2.1.222026-02-1773595Update dependencies
2.1.212026-02-1271030Use user_account_analytics for connection check to support all permission sets
2.1.202026-02-1073173Update dependencies
2.1.192026-02-0372668Update dependencies
2.1.182026-01-2069629Update dependencies
2.1.172025-10-2968961Update dependencies
2.1.162025-10-2168213Update dependencies
2.1.152025-10-1467808Update dependencies
2.1.142025-10-0762329Update dependencies
2.1.132025-10-0667105Promoting release candidate 2.1.13-rc.2 to a main version.
2.1.13-rc.22025-10-0367025Add timeout status for reports
2.1.13-rc.12025-09-3066755Migrate to manifest-only
2.1.122025-09-3066820Promoting release candidate 2.1.12-rc.1 to a main version.
2.1.12-rc.12025-09-2966564Migrate Custom Reports streams
2.1.112025-09-2966737Promoting release candidate 2.1.11-rc.1 to a main version.
2.1.11-rc.12025-09-2366560Migrate Targeting Analytics Reports streams
2.1.102025-09-2266565Promoting release candidate 2.1.10-rc.1 to a main version.
2.1.10-rc.12025-09-1666187Migrate Analytics Reports streams
2.1.92025-09-1666281Promoting release candidate 2.1.9-rc.2 to a main version.
2.1.9-rc.22025-09-1266211Add APIBudget and backoff strategy for analytics streams
2.1.9-rc.12025-09-0565960feat(source-pinterest): Update CDK to v6
2.1.82025-06-2161920Update dependencies
2.1.72025-06-1461067Update dependencies
2.1.62025-05-2460136Update dependencies
2.1.52025-05-0459069Update dependencies
2.1.42025-04-1958524Update dependencies
2.1.32025-04-1257926Update dependencies
2.1.22025-04-0557337Update dependencies
2.1.12025-03-2956721Update dependencies
2.1.02025-02-0353135Added Account Id filter to allow retrieving data for a specific ad account
2.0.322025-03-2255055Update dependencies
2.0.312025-02-2354581Update dependencies
2.0.302025-02-1553977Update dependencies
2.0.292025-02-0153001Update dependencies
2.0.282025-01-2552502Update dependencies
2.0.272025-01-1151377Update dependencies
2.0.262025-01-0450933Update dependencies
2.0.252024-12-2850710Update dependencies
2.0.242024-12-2150302Update dependencies
2.0.232024-12-1449040Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
2.0.222024-11-0448280Update dependencies
2.0.212024-10-2947074Update dependencies
2.0.202024-10-1246815Update dependencies
2.0.192024-10-0546482Update dependencies
2.0.182024-09-2846104Update dependencies
2.0.172024-09-2145838Update dependencies
2.0.162024-09-1445566Update dependencies
2.0.152024-09-0745283Update dependencies
2.0.142024-08-3145060Update dependencies
2.0.132024-08-2444752Update dependencies
2.0.122024-08-1744346Update dependencies
2.0.112024-08-1243838Update dependencies
2.0.102024-08-1043642Update dependencies
2.0.92024-08-0343280Update dependencies
2.0.82024-07-3039559Ensure config_error when state has improper format and update CDK version
2.0.72024-07-2742603Update dependencies
2.0.62024-07-2042343Update dependencies
2.0.52024-07-1341765Update dependencies
2.0.42024-07-1041449Update dependencies
2.0.32024-07-0639972Update dependencies
2.0.22024-06-1039367Fix type error when start date was not provided
2.0.12024-06-0439037[autopull] Upgrade base image to v1.2.1
2.0.02024-05-2037698Migrate to low-code
1.3.32024-04-2436655Schema descriptions and CDK 0.80.0
1.3.22024-04-0836912Fix icon
1.3.12024-04-0336806Update airbyte-cdk count bug to emit recordCount as float
1.3.02024-03-1936267Pin airbyte-cdk version to ^0
1.2.02024-02-2035465Per-error reporting and continue sync on stream failures
1.1.12024-02-1235159Manage dependencies with Poetry.
1.1.02023-11-2232747Update docs and spec. Add missing placement_traffic_type field to AdGroups stream
1.0.02023-11-1632595Add airbyte_type: timestamp_without_timezone to date-time fields across all streams. Rename Advertizer* streams to Advertiser*
0.8.22023-11-2032672Fix backoff waiting time
0.8.12023-11-1632601added ability to create custom reports
0.8.02023-11-1632592Make start_date optional; add suggested streams; add missing fields
0.7.22023-11-0832299added default AvailabilityStrategy, fixed bug which cases duplicated requests, added new streams: Catalogs, CatalogsFeeds, CatalogsProductGroups, Audiences, Keywords, ConversionTags, CustomerLists, CampaignTargetingReport, AdvertizerReport, AdvertizerTargetingReport, AdGroupReport, AdGroupTargetingReport, PinPromotionReport, PinPromotionTargetingReport, ProductGroupReport, ProductGroupTargetingReport, ProductItemReport, KeywordReport
0.7.12023-11-0132078handle non json response
0.7.02023-10-2531876Migrated to base image, removed token based authentication mthod becuase access_token is valid for 1 day only
0.6.02023-07-2528672Add report stream for CAMPAIGN level
0.5.32023-07-0527964Add id field to owner field in ad_accounts stream
0.5.22023-06-0226949Update BoardPins stream with note property
0.5.12023-05-1125984Add pattern for start_date
0.5.02023-05-1726188Add product_tags field to the BoardPins stream
0.4.02023-05-1626112Add is_standard field to the BoardPins stream
0.3.02023-05-0925915Add creative_type field to the BoardPins stream
0.2.62023-04-2625548Fix format issue for boards stream schema for fields with date-time
0.2.52023-04-190Update AMOUNT_OF_DAYS_ALLOWED_FOR_LOOKUP to 89 days
0.2.42023-02-2523457Add missing columns for analytics streams for pinterest source
0.2.32023-03-0123649Fix for HTTP - 400 Bad Request when requesting data >= 90 days
0.2.22023-01-2722020Set AvailabilityStrategy for streams explicitly to None
0.2.12022-12-1520532Bump CDK version
0.2.02022-12-1320242Add data-type normalization up to the schemas declared
0.1.92022-09-0615074Add filter based on statuses
0.1.82022-10-2118285Fix type of start_date
0.1.72022-09-2917387Set start_date dynamically based on API restrictions.
0.1.62022-09-2817304Use CDK 0.1.89
0.1.52022-09-1616799Migrate to per-stream state
0.1.42022-09-0616161Add ability to handle 429 - Too Many Requests error with respect to Max Rate Limit Exceeded Error
0.1.32022-09-0216271Add support of OAuth2.0 authentication method
0.1.22021-12-2210223Fix naming of AD_ID and AD_ACCOUNT_ID fields
0.1.12021-12-229043Update connector fields title/description
0.1.02021-10-297493Release Pinterest CDK Connector
</details>