Pinterest API Integration - Pins, Boards & Analytics

Pinterest is about discovery, not just a feed. People come here to find ideas and save them for later. The API reflects this - “saves” are the key metric, not likes.

Supported Content Types

Pins: 1 image or 1 video.
Carousel Pins: 2 to 5 images in one Pin. See Carousel Pins.

Quirks & Gotchas

Board Name is Required

You can’t pin to thin air. Every Pinterest post needs boardName. Use a board from socialAccount.channels.

Terminology

Likes are often referred to as Saves or Reactions depending on context. We normalize them in our schema.
Video Pins: Only video pins have true “View” counts. Static image pins just show impressions in the views field.

Media Limits

Constraint	Value
Files	1 image or video, or 2-5 images for a carousel (required)
Carousel images	Same aspect ratio, no videos
Video max size	2 GB
Video aspect ratio	1:2 to 1.91:1
Video duration	4s - 15 min
Image max size	5 MB

See Platform Limits for more details.

Text & Field Limits

Field	Limit
`text`	Max 100 characters
`description`	Max 800 characters
`link`	Max 2,048 characters
`altText`	Max 500 characters
`note`	Max 500 characters
`boardName`	Required. Use a board name from `socialAccount.channels`.

Post Options

Field	Type	Description
`boardName`	`string`	Required. Board name from `socialAccount.channels`.
`text`	`string`	Pin title. Max 100 characters.
`description`	`string`	Pin description. Max 800 characters.
`uploadIds`	`string[]`	One image or video, or 2-5 images for a carousel Pin. The order is the slide order.
`carouselItems`	`object[]`	Optional per-slide `title`, `description` and `link` for a carousel Pin. See Carousel Pins.
`thumbnail`	`string`	URL to an uploaded thumbnail image.
`link`	`string`	Destination URL. Max 2,048 characters.
`altText`	`string`	Image alt text. Max 500 characters.
`note`	`string`	Private note. Max 500 characters.
`dominantColor`	`string`	Hex color used while the image loads.

{
  "teamId": "team_123",
  "title": "Pinterest spring collection",
  "status": "SCHEDULED",
  "postDate": "2026-06-01T15:00:00.000Z",
  "socialAccountTypes": ["PINTEREST"],
  "data": {
    "PINTEREST": {
      "boardName": "Product ideas",
      "text": "New spring collection",
      "description": "A clean, bright look for small teams",
      "uploadIds": ["upl_img_1"],
      "link": "https://example.com/spring"
    }
  }
}

Carousel Pins

Send 2 to 5 image uploads in uploadIds and they’re published as one carousel Pin, in that order.

All images need the same aspect ratio (we allow 1% for rounding). Otherwise the post is rejected with 400.
No videos in a carousel, and each upload can appear only once.
Every slide uses the Pin’s text, description and link by default. To set them per slide, add carouselItems: one entry per slide you want to change, matched by uploadId. A missing or empty field falls back to the Pin value.

`carouselItems[]` field	Type	Description
`uploadId`	`string`	Required. One of the `uploadIds`.
`title`	`string`	Slide title. Max 100 characters.
`description`	`string`	Slide description. Max 800 characters.
`link`	`string`	Slide destination URL. Max 2,048 characters.

{
  "data": {
    "PINTEREST": {
      "boardName": "Product ideas",
      "text": "Spring collection",
      "description": "Five looks for small teams",
      "link": "https://example.com/spring",
      "uploadIds": ["upl_img_1", "upl_img_2", "upl_img_3"],
      "carouselItems": [
        { "uploadId": "upl_img_2", "title": "The desk setup", "link": "https://example.com/spring/desk" }
      ]
    }
  }
}

carouselItems needs at least 2 uploadIds. Pinterest downloads every slide while creating the Pin, so a carousel takes longer to publish than a single image. Post history import: carousel Pins are imported with the first slide as the thumbnail. With importCarousels: true, every slide is added to extraData.media[]. See Import Posts.

Analytics

For general analytics concepts (refresh rates, data retention, what “Returns 0” means), see the Analytics Overview.

Profile Analytics

Period: Rolling window (30 days). Aggregated across all pin analytics.

Metric	Description	Note
`impressions`	Total impressions
`impressionsUnique`	-	Same as impressions (Pinterest doesn’t distinguish)
`views`	Video views	Defaults to impressions if no video pins
`viewsUnique`	-	Same as views
`likes`	Saves
`comments`	-	Returns `0` (not provided at profile level)
`postCount`	Total pins
`followers`	Followers
`following`	Following

Post Analytics

Period: Mixed (30-day rolling window for views/impressions, Lifetime for engagement).

Metric	Description	Note
`impressions`	Impressions	30-day window
`impressionsUnique`	-	Same as impressions
`views`	Video views	30-day window; defaults to impressions for static pins
`viewsUnique`	-	Same as views
`likes`	Total reactions	Lifetime
`comments`	Total comments	Lifetime
`shares`	-	Returns `0` (not tracked by Pinterest)
`saves`	Saves	30-day window

Quirks

Views are only meaningful for video pins. Static pins show impressions in the views field as a fallback.
Profile-level comments are not available through the Pinterest API.
Shares are not a concept Pinterest tracks.
Post analytics use a mixed approach: some metrics are rolling window, others are lifetime. It’s confusing, but it’s what Pinterest gives us.

Raw Analytics

Pinterest profile raw analytics include the user analytics payload, follower list, and following list we used to build the standard numbers.

{
  "analytics": {
    "summary_metrics": {
      "IMPRESSION": 54000,
      "SAVE": 820,
      "VIDEO_START": 9100
    }
  },
  "followers": {
    "items": [{ "username": "follower_1" }]
  },
  "following": {
    "items": [{ "username": "brand_1" }]
  }
}

Pinterest post raw analytics store the Pin analytics response for the requested date range.

{
  "externalId": "1234567890",
  "summary_metrics": {
    "IMPRESSION": 6400,
    "SAVE": 94,
    "PIN_CLICK": 220,
    "OUTBOUND_CLICK": 58,
    "VIDEO_START": 0
  }
}

API Documentation

Platforms

Guides

Endpoints

Pinterest

Supported Content Types

Quirks & Gotchas

Board Name is Required

Terminology

Media Limits

Text & Field Limits

Post Options

Carousel Pins

Analytics

Profile Analytics

Post Analytics

Quirks

Raw Analytics

​Supported Content Types

​Quirks & Gotchas

​Board Name is Required

​Terminology

​Media Limits

​Text & Field Limits

​Post Options

​Carousel Pins

​Analytics

​Profile Analytics

​Post Analytics

​Quirks

​Raw Analytics

Supported Content Types

Quirks & Gotchas

Board Name is Required

Terminology

Media Limits

Text & Field Limits

Post Options

Carousel Pins

Analytics

Profile Analytics

Post Analytics

Quirks

Raw Analytics