Skip to main content
Pinterest is a visual discovery engine where users find ideas and inspiration. The connector uses the Pinterest API v5 to extract user account, ad accounts, campaigns, ad groups, ads, and their analytics for advertising and reporting.

​
Configuring Pinterest as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Pinterest option from the list of connectors. Click Next and you’ll be prompted to add your access.

​
1. Add account access

You’ll need to authorize Nekt to access your Pinterest data via OAuth 2.0. Complete the Pinterest OAuth flow so that an access token is available for the connector. The following configurations are available:
  • Access Token: (Required) OAuth 2.0 access token. Obtain it by completing the Pinterest OAuth flow: user authorizes your Pinterest App, then you exchange the authorization code for an access token using your App ID and App Secret. Do not commit this value; use environment variables or secrets.
  • Start date: (Optional) Start date for analytics streams (user account, ad account, campaigns, ad groups, ads). Format: YYYY-MM-DD. If omitted, the last 30 days are used. Non-analytics streams are not filtered by this date. Note: The Pinterest API only provides analytics for the last 90 days; older start dates are automatically capped.
  • Lookback window (days): (Optional, default: 28) Pinterest may update analytics data for recent days. Nekt re-fetches data within this window so the last N days are always up-to-date. Only applies to analytics streams.
Once you’re done, click Next.

​
2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.
Tip: The stream can be found more easily by typing its name.
Select the streams and click Next.

​
3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
  • Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
  • Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
  • Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
  • Sync Type: you can choose between INCREMENTAL and FULL_TABLE. All streams use full table sync by default.
Once you are done configuring, click Next.

​
4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click Next to finalize the setup.

​
5. Check your new source

You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your Catalog, you need at least one successful source run.

​
Streams and Fields

Below you’ll find all available data streams from Pinterest (API v5) and their corresponding fields. Streams such as campaigns, ad_groups, and ads (and their analytics) depend on ad_accounts and are synced per ad account.
Single record with the authenticated user’s Pinterest account.Key Fields:
  • id - User account ID
  • username - Username
  • account_type - Account type (e.g. BUSINESS)
  • profile_image - Profile image URL
  • website_url - Website URL
  • business_name - Business name
  • business_id - Business ID
  • about - About/bio
User account analytics (metrics over the period defined by Start date). Returns daily or aggregate metrics.Key Fields:
  • date - Date (YYYY-MM-DD) for daily metrics
  • data_status - Data status
  • metrics - JSON string containing metric blocks (e.g. summary_metrics, daily_metrics with ENGAGEMENT, IMPRESSION, SAVE, etc.)
List of ad accounts (paginated). Parent stream for campaigns, ad_groups, ads and all analytics streams that are per ad account.Key Fields:
  • id - Ad account ID (e.g. act_123)
  • name - Ad account name
  • owner - Object with id and username (owner user)
  • country - Country code
  • currency - Currency code
  • permissions - Permission scopes for the ad account
  • created_time, updated_time - Unix timestamps
Ad account-level analytics by day. Child of ad_accounts; uses Start date for the date range.Key Fields:
  • ad_account_id - Ad account ID (from context)
  • date - Date (YYYY-MM-DD)
  • Metrics (spend, impressions, etc.) as returned by the API
List of campaigns for each ad account. Child of ad_accounts.Key Fields:
  • ad_account_id - Ad account ID (from context)
  • id - Campaign ID
  • name - Campaign name
  • status - Status (e.g. ACTIVE, PAUSED)
  • objective_type - Objective type
  • created_time, updated_time - Unix timestamps
Campaign-level analytics by day. Child of ad_accounts; uses Start date for the date range.Key Fields:
  • ad_account_id - Ad account ID (from context)
  • date - Date (YYYY-MM-DD)
  • campaign_id - Campaign ID
  • Metrics (spend, impressions, etc.)
List of ad groups for each ad account. Child of ad_accounts.Key Fields:
  • ad_account_id - Ad account ID (from context)
  • id - Ad group ID
  • name - Ad group name
  • campaign_id - Campaign ID
  • status - Status
  • created_time, updated_time - Unix timestamps
Ad group-level analytics by day. Child of ad_accounts; uses Start date for the date range.Key Fields:
  • ad_account_id - Ad account ID (from context)
  • date - Date (YYYY-MM-DD)
  • ad_group_id - Ad group ID
  • Metrics (spend, impressions, etc.)
List of ads for each ad account. Child of ad_accounts.Key Fields:
  • ad_account_id - Ad account ID (from context)
  • id - Ad ID
  • name - Ad name
  • ad_group_id - Ad group ID
  • campaign_id - Campaign ID
  • status - Status
  • created_time, updated_time - Unix timestamps
Ad-level analytics by day. Child of ad_accounts; uses Start date for the date range.Key Fields:
  • ad_account_id - Ad account ID (from context)
  • date - Date (YYYY-MM-DD)
  • ad_id - Ad ID
  • Metrics (spend, impressions, etc.)

​
Data Model

The following diagram illustrates the main relationships between streams. ad_accounts is the parent for campaigns, ad_groups, ads and all analytics streams that are scoped per ad account.

​
Implementation Notes

  • Authentication: The connector expects an OAuth 2.0 access_token. Obtain it via the Pinterest OAuth flow using your Pinterest App (App ID and App Secret). Do not store the secret in code; use environment variables or a secrets manager.
  • Analytics date range: Analytics streams use the Start date config (or last 30 days if omitted) up to today. 90-day limit: The Pinterest API does not provide analytics data older than 90 days; this is an API limitation and cannot be worked around (e.g. by chunking requests). If you set a start date older than 90 days, the connector will request from (today − 90 days) to today. Lookback window (default 28 days): Nekt re-fetches the last N days on each run so recently changing metrics stay up-to-date.
  • Parent streams: campaigns, ad_groups, ads, and all *_analytics streams depend on ad_accounts. Ensure ad_accounts is selected when syncing these streams.
  • Pagination: List streams (ad_accounts, campaigns, ad_groups, ads) use Pinterest v5 bookmark pagination (page_size and bookmark cursor).