Advanced Analytica Advanced Analytica: IBOM
← All connectors
Pinterest logo

Source connector

Pinterest

Set up Pinterest as a source and move its data into your chosen destination.

Version 2.4.3 certified generally available

Pinterest

Use this page to set up the Pinterest source connector and find reference information.

Prerequisites

Pinterest doesn’t let you configure permissions during OAuth authentication for Airbyte Cloud. It therefore requests these permissions during authentication:

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

For more information about the scopes required for Pinterest OAuth, see Pinterest API Scopes documentation.

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

Each connector stream requires specific Pinterest OAuth scopes:

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

Some streams may not return data if your Pinterest account has limited permissions. The connector validates your connection through the user_account_analytics stream.

This stream only requires the user_accounts:read scope, which is available to all authenticated Pinterest users.

Pinner data access for newer apps

Pinterest may return 403 PINNER_DATA_ACCESS_DENIED for the board_sections, board_pins, and board_section_pins streams in specific circumstances.

This applies if your Pinterest app was registered on or after September 14, 2026. It continues until Pinterest approves the app for pinner data access.

This can happen when the connector reads boards that don’t belong to the account that authorised the app. For example, it can affect boards returned for a business ad account set in Account ID.

You don’t need extra approval to read the authorising account’s boards and Pins. Apps registered before that date aren’t affected.

Contact your Pinterest account manager to request approval. For details, see Pinterest changelog.

Set up the connector

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Pinterest from the Source type dropdown.
  4. Enter a name for the Pinterest connector.
  5. The OAuth2.0 authorisation method is selected by default. Click Authenticate your Pinterest account. Log in and authorise your Pinterest account.
  6. (Optional) For Start Date, enter the date in YYYY-MM-DD format. The connector replicates data from this date onwards. If you don’t enter a date, the connector uses each stream’s maximum lookback period. Analytics streams can look back up to 90 days. Report streams can look back up to 913 days.
  7. (Optional) Select one or more status values from the dropdown menu. Available values are ACTIVE, PAUSED, and ARCHIVED. For the ads, ad_groups, and campaigns streams, a status excludes records that don’t match. If you don’t specify a status, the source defaults to ACTIVE and PAUSED.
  8. (Optional) Add custom reports if needed. See the corresponding section for more information.
  9. (Optional) Enter an Ad Account ID. The source then retrieves data only for that specific Pinterest Ad Account.
  10. (Optional) Set Number of concurrent workers to control the connector’s parallel requests during a sync. The default is 2. Higher values make syncs faster but increase rate-limit pressure. Reduce this value if you encounter rate-limit errors.
  11. Click Set up source.

For Airbyte Open Source:

  1. Go to the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. On the Set up the source page, select Pinterest from the Source type dropdown.
  4. Enter a name for the Pinterest connector.
  5. The OAuth2.0 authorisation 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 from this date onwards. If you don’t enter a date, the connector uses each stream’s maximum lookback period. Analytics streams can look back up to 90 days. Report streams can look back up to 913 days.
  7. (Optional) Select one or more status values from the dropdown menu. Available values are ACTIVE, PAUSED, and ARCHIVED. For the ads, ad_groups, and campaigns streams, a status excludes records that don’t match. If you don’t specify a status, the source defaults to ACTIVE and PAUSED.
  8. (Optional) Add custom reports if needed. See the corresponding section for more information.
  9. (Optional) Enter an Ad Account ID. The source then retrieves data only for that specific Pinterest Ad Account.
  10. (Optional) Set Number of concurrent workers to control the connector’s parallel requests during a sync. The default is 2. Higher values make syncs faster but increase rate-limit pressure. Reduce this value if you encounter rate-limit errors.
  11. Click Set up source.

Attribution window

Use Attribution Window to control how many previous days the connector rereads during each incremental sync. This setting applies to report and analytics streams.

Pinterest updates past metrics while it continues attributing conversions. Match this setting to your reports’ longest click, engagement, or view window to capture late updates.

The default is 0, so the connector reads only new days. You can set it to no more than 60.

The connector always respects a stream’s own date limit when it’s shorter than the lookback. Hourly custom reports can look back 2 days. Analytics streams can look back 89 days, and product item reports 91 days.

The connector writes reread days again. Use the Append + Deduped sync mode and choose a primary key in the connection to keep one row per day.

Supported sync modes

The Pinterest source connector supports these sync modes:

Supported streams

Custom reports

Create personalised analytics reports for your account with custom reports. Tailor each report to your needs by choosing these properties:

  1. Name: Provides a unique identifier for the report.
  2. Level: Sets the data aggregation level, with options including ADVERTISER, CAMPAIGN, and AD_GROUP. The default level is ADVERTISER.
  3. Granularity: Sets the data granularity, such as TOTAL, DAY, or HOUR. The default is TOTAL, which aggregates metrics across the specified date range.
  4. Columns: Identifies the data columns included in the report.
  5. Click Window Days (Optional): Sets the conversion attribution period, in days, for a pin click action. This applies to Pinterest Tag conversion metrics. Valid values are 0, 1, 7, 14, 30, and 60. It defaults to 30 days if you don’t specify a value. Set it to 0 to disable click attribution.
  6. Engagement Window Days (Optional): Sets the conversion attribution period, in days, for 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. It defaults to 30 days if you don’t specify a value. Set it to 0 to disable engagement attribution.
  7. View Window Days (Optional): Sets the conversion attribution window, in days, for a view action. This applies to Pinterest Tag conversion metrics. Valid values are 0, 1, 7, 14, 30, and 60. It defaults to 30 days if you don’t specify a value. Set it to 0 to disable view attribution.
  8. Conversion Report Time (Optional): Sets the date used to report returned conversion metrics. A conversion event has two associated dates: the ad interaction date and the conversion completion date. The default is TIME_OF_AD_ACTION.
  9. Attribution Types (Optional): Lists the report’s attribution types, such as INDIVIDUAL or HOUSEHOLD.
  10. Campaign Statuses (Optional): Filters custom report results by campaign status. Select from RUNNING, PAUSED, NOT_STARTED, COMPLETED, ADVERTISER_DISABLED, ARCHIVED, DRAFT, and DELETED_DRAFT. Include ARCHIVED to report on archived campaigns. If you select more than six values, the connector splits them across multiple Pinterest report requests.
  11. Ad Group Statuses (Optional): Filters custom report results by ad group status. Select from RUNNING, PAUSED, NOT_STARTED, COMPLETED, ADVERTISER_DISABLED, ARCHIVED, DRAFT, and DELETED_DRAFT. If you select more than six values, the connector splits them across multiple Pinterest report requests.
  12. Ad Statuses (Optional): Filters custom report results by ad status. Select from APPROVED, PAUSED, PENDING, REJECTED, ADVERTISER_DISABLED, ARCHIVED, DRAFT, and DELETED_DRAFT. If you select more than six values, the connector splits them across multiple Pinterest report requests. Product Item level reports don’t support this filter.
  13. Start Date (Optional): Sets the report’s start date in YYYY-MM-DD format. It defaults to the report API’s latest allowed date, which is 913 days from today.

For detailed guidance on creating custom reports, see Pinterest API documentation.

Performance considerations

The Pinterest rate limits restricts the connector. The Pinterest API applies rate limits by endpoint category.

For example, the ads_analytics category allows 300 requests per minute with standard access. The ads_read and org_read categories allow 1,000 requests per minute.

For details, see Pinterest rate limits documentation.

When the connector receives a rate-limit response, it waits based on the X-RateLimit-Reset header and retries automatically.

Reduce Number of concurrent workers to lower rate-limit pressure, although syncs will take longer. The default is 2, and the range is 1–40.

The connector sends custom report status filters in chunks of no more than six values per dimension.

Selecting many campaign, ad group, and ad statuses multiplies asynchronous report-creation requests by ceil(campaign_statuses / 6) × ceil(ad_group_statuses / 6) × ceil(ad_statuses / 6) for each account and date window. The maximum is 8x because each field has eight possible values.

Each entity has exactly one status, so chunked requests return separate row sets. No rows are duplicated or lost.

Selecting more than six values requires the report level to match or sit below the filtered dimension. For example, more than six ad statuses require a PIN_PROMOTION-level report.

At broader levels, several chunks would return the same aggregated rows. The connector therefore rejects these configurations.

The connector automatically retries rate-limited report calls. If you reach analytics rate limits, select fewer statuses or reduce concurrent workers.

IP allow list

If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Changelog

Expand to review
VersionDatePull RequestSubject
2.4.32026-11-1091197Declare the refreshed access_token and token_expiry_date in the spec so the access token is masked as a secret
2.4.22026-11-1091673Update dependencies
2.4.12026-11-0389338Update dependencies
2.4.02026-10-1589007Add attribution_window setting to re-read recent report and analytics dates on incremental syncs
2.3.62026-10-1388724Update dependencies
2.3.52026-10-0687990Update dependencies
2.3.42026-09-2987273Update dependencies
2.3.32026-09-2286737Update dependencies
2.3.22026-09-1586186Update dependencies
2.3.12026-09-0885598Update dependencies
2.3.02026-08-2480303Split Pinterest custom report status filters into multiple API calls when more than six values are selected.
2.2.122026-08-1884706Update dependencies
2.2.112026-08-1183997Update dependencies
2.2.102026-07-2883194Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override
2.2.92026-07-281082Roll Cloud back to 2.2.7 — 2.2.8 is built on SDM 7.23.7, which breaks bundled custom components
2.2.82026-07-2883033Update dependencies
2.2.72026-07-2182553Update dependencies
2.2.62026-07-1481972Update dependencies
2.2.52026-06-3081182Update dependencies
2.2.42026-06-2380579Update dependencies
2.2.32026-06-1679987Update dependencies
2.2.22026-06-1579693Handle Pinterest rate limits during report download target refresh and reduce default concurrency.
2.2.12026-06-1078496Refresh Pinterest async report download URLs immediately before fetching reports.
2.2.02026-06-1079655Promotes to stable release.
2.2.0-rc.12026-06-0978320Added optional custom report status filters so archived campaigns, ad groups, and ads can be included in Pinterest analytics reports.
2.1.302026-06-0979465Update dependencies
2.1.292026-06-0275841Update dependencies
2.1.282026-06-0178538Promoted release candidate to GA
2.1.28-rc.42026-05-2778466Remove the HTTP API budget while keeping default concurrency at 4 for continued tuning.
2.1.28-rc.32026-05-2678432Set default concurrency to 4 and use the standard num_workers override while preserving the Pinterest API budget.
2.1.28-rc.22026-05-2178345Increase default concurrency to 5 for the source-pinterest Phase 1 tuning cohort.
2.1.28-rc.12026-05-1876952Concurrency tuning (Path A): bump default_concurrency default to 4 via the num_threads fallback. No user-visible spec changes.
2.1.272026-04-0775485Add maxLength validation to account_id field to reject values longer than 18 characters at config time
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 method because 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
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.