Skip to main content

Documentation Index

Fetch the complete documentation index at: https://info.bundle.social/llms.txt

Use this file to discover all available pages before exploring further.

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. That’s it - one file per pin.

​
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

ConstraintValue
Files1 (image or video, required)
Video max size1 GB
Video aspect ratio1:2 to 1.91:1
Video duration4s - 15 min
Image max size5 MB
See Platform Limits for more details.

​
Text & Field Limits

FieldLimit
textMax 100 characters
descriptionMax 800 characters
linkMax 2,048 characters
altTextMax 500 characters
noteMax 500 characters
boardNameRequired. Use a board name from socialAccount.channels.

​
Post Options

FieldTypeDescription
boardNamestringRequired. Board name from socialAccount.channels.
textstringPin title. Max 100 characters.
descriptionstringPin description. Max 800 characters.
uploadIdsstring[]One image or video upload.
thumbnailstringURL to an uploaded thumbnail image.
linkstringDestination URL. Max 2,048 characters.
altTextstringImage alt text. Max 500 characters.
notestringPrivate note. Max 500 characters.
dominantColorstringHex 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"
    }
  }
}

​
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.
MetricDescriptionNote
impressionsTotal impressions
impressionsUnique-Same as impressions (Pinterest doesn’t distinguish)
viewsVideo viewsDefaults to impressions if no video pins
viewsUnique-Same as views
likesSaves
comments-Returns 0 (not provided at profile level)
postCountTotal pins
followersFollowers
followingFollowing

​
Post Analytics

Period: Mixed (30-day rolling window for views/impressions, Lifetime for engagement).
MetricDescriptionNote
impressionsImpressions30-day window
impressionsUnique-Same as impressions
viewsVideo views30-day window; defaults to impressions for static pins
viewsUnique-Same as views
likesTotal reactionsLifetime
commentsTotal commentsLifetime
shares-Returns 0 (not tracked by Pinterest)
savesSaves30-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
  }
}