Skip to content

Pinterest Analytics API

The Pinterest Analytics API brings Pin impressions, Pin saves, and Pin clicks into a product, reporting workflow, automation, or AI system through one API.

Recent Pins Request
curl "{{API_BASE_URL}}/v1/analytics?source=platform&accountId=acc_pin_111&platform=pinterest&limit=10" \
    -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl "{{API_BASE_URL}}/v1/analytics?source=platform&accountId=acc_pin_111&platform=pinterest&limit=10" \

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

Use it to analyze recent Pins directly from connected Pinterest accounts, look up an existing pin by its Pinterest pin ID, and filter results for the reporting period you need. The same response shape supports dashboards and reports that compare discovery, interest, and traffic across Pins without building a separate Pinterest analytics integration.

What the Pinterest Analytics API returns and when to use it

The Pinterest Analytics API returns Pin-level metrics for supported Pinterest Pins, including impressions, reactions mapped as likes, comments, saves, and clicks. Impressions show discovery, saves signal that people chose to keep a Pin for later, and clicks show movement toward the Pin or its destination. A calculated engagement rate may also be returned when the underlying data supports it. Use recent-pins retrieval when you need a list to populate a dashboard, single-pin lookup when you already have an existing pin ID, and date-range retrieval when a report covers a defined period.

Exact request contract: recent pins, single pin, and date range

For recent Pins, request analytics with source=platform, the connected accountId, platform=pinterest, and a limit. The worked example in the Recent Pins Request shows the exact query shape, and the Recent Pins Response shows the corresponding response shape. For an existing pin, supply its Pinterest pin ID alongside platform=pinterest and the connected accountId to fetch figures for that one Pin. For a reporting period, add fromDate and toDate so the response is scoped to the dates your product needs. Choose recent-pins retrieval for discovery lists, single-pin lookup for a known Pin, and date-range filtering for periodic reporting.

Response field map and nullable metrics

The response separates pagination and totals from per-Pin data. Each entry carries a source, a postId that can be null for platform-sourced Pins, content, publishedAt, an aggregated metrics object, and a platforms array with Pinterest-specific identifiers and metrics. Read aggregated for cross-platform rollups and the Pinterest entry in platforms for Pin-specific values such as platformPostId and platformPostUrl. Several metrics can be null, including reach, shares, views, and engagementRate, so treat null as unsupported or unavailable for that Pin rather than as zero. The Response Field Map table lists each field and how to handle it, and the Edge Cases table covers null postId, null metrics, and empty results.

Closeups vs outbound clicks and interpreting saves and clicks

Closeups and outbound clicks answer different questions. A closeup is an in-app tap that enlarges a Pin for closer inspection, so it reflects curiosity about the creative itself. An outbound click follows the destination URL away from Pinterest, so it reflects referral traffic. Pin clicks in the unified response include the click activity exposed by Pinterest, so label outbound clicks separately in your dashboard when you need to distinguish on-Pinterest interest from off-Pinterest traffic. Saves add a third signal: a Pin with strong saves but modest clicks may be valuable as a keep-and-revisit asset even when it sends less immediate traffic.

Existing pins not published through the API

You do not need to limit analytics to Pins published through the API. Set source=platform and provide the connected Pinterest accountId, and recent Pins can be pulled directly from Pinterest. That makes the API suitable for backfilling performance for an existing pin catalog, auditing older Pins, and comparing new Pins against established ones. When a Pin was not published through the API, expect postId to be null in the response and rely on platformPostId and platformPostUrl to identify the Pin.

Account connection and Business account note

Connect Pinterest through the provider's OAuth flow instead of maintaining the Pinterest OAuth integration yourself. The provider handles the underlying Pinterest API connection and token management, while your application uses its own API key and the connected Pinterest account ID. Pinterest provides its full organic analytics capabilities around Business accounts, and this workflow is designed around connected Pinterest Business accounts, so connect that account first and use its returned account ID for analytics requests. If a request fails, check that the accountId belongs to a connected Pinterest account, that platform is set to pinterest, and that the Pin ID matches an existing pin on that account before retrying.

Worked example and edge cases

Start with the Recent Pins Request to validate your accountId, platform value, and limit handling, then inspect the Recent Pins Response for null metrics and null postId handling. Add fromDate and toDate only when you need a bounded reporting window, and use single-pin lookup when you already know the Pin ID. In dashboards, show impressions, saves, and clicks together so discovery, keep intent, and traffic are not confused, and keep closeups distinct from outbound clicks when both are available. The FAQs below answer the most common implementation questions about metrics, credentials, Business accounts, and where the data can be used.

Input Contract
ParameterValue or formatUse
sourceplatformPull recent Pins directly from Pinterest for the connected account
accountIdConnected Pinterest account IDIdentifies which connected Pinterest account to query
platformpinterestSelects Pinterest analytics
limitExample: 10Controls how many recent Pins are returned
fromDateReporting start dateScopes analytics to the start of the reporting period
toDateReporting end dateScopes analytics to the end of the reporting period
Pin IDPinterest pin IDLooks up an existing pin together with platform=pinterest and accountId

Single-pin lookup is described in source prose as a Pinterest pin ID with platform=pinterest and accountId; no additional parameters are invented here.

Response Field Map
FieldLocationHandling
successTop levelCheck before reading results
totalTop levelTotal matching Pins for the request
pageTop levelCurrent page of results
limitTop levelPage size used for the request
postsTop levelArray of Pin analytics entries
sourceEach postExample value: platform
postIdEach postCan be null for platform-sourced Pins
contentEach postPin content as returned
publishedAtEach postPublication timestamp as returned
aggregatedEach postCross-platform rollup of metrics
platformsEach postPer-platform entries, including Pinterest
platformPostIdPinterest platform entryPinterest identifier for the Pin
platformPostUrlPinterest platform entryURL of the Pin on Pinterest
metricsPinterest platform entryPinterest-specific metric values
impressionsaggregated and metricsPin impressions; discovery signal
likesaggregated and metricsReactions mapped as likes
commentsaggregated and metricsComment count as returned
savesaggregated and metricsPin saves; keep-and-revisit signal
clicksaggregated and metricsPin clicks as exposed by Pinterest
reachaggregated and metricsCan be null; do not treat null as zero
sharesaggregated and metricsCan be null; do not treat null as zero
viewsaggregated and metricsCan be null; do not treat null as zero
engagementRateaggregated and metricsCalculated engagement rate; can be null

Nullability follows the captured response example; closeups are named in FAQ metrics but no response field name was captured.

Edge Cases and Failure Checks
CaseWhat you seeHow to handle it
postId is nullPlatform-sourced Pin with no internal post IDIdentify the Pin with platformPostId and platformPostUrl
reach, shares, views, or engagementRate is nullMetric unsupported or unavailable for that PinRender as unavailable, not zero, and exclude from averages that require a value
Empty posts arrayNo Pins matched the account, platform, limit, or date rangeShow an empty state and check accountId, platform=pinterest, and fromDate/toDate
Existing pin not foundPin ID does not match a Pin on the connected accountVerify the Pin ID and that accountId is the connected Pinterest account
Closeups needed but not in response fieldsFAQ names closeups as a metric without a captured field nameDo not invent a field; confirm the field name before building UI around it

Edge handling is derived from the captured example fields and FAQ definitions.

Frequently asked questions

What Pinterest analytics metrics can I get through the API?

Expect per-Pin figures for impressions, saves, clicks, closeups, and a computed engagement rate where data permits. Together they show how often a Pin was seen, kept, opened, and used to send traffic onward.

Do I need my own Pinterest API credentials or developer app?

No separate Pinterest developer setup is required on your side. Authentication and token handling sit with the provider, so your code supplies the provider API key plus the connected account identifier.

Do I need a Pinterest Business account for analytics?

The workflow described here targets connected Pinterest Business accounts, because Pinterest centres its organic analytics around that account type. Link the relevant account first, then pass back the identifier it returns.

What is the difference between closeups and outbound clicks on Pinterest?

Opening a Pin for a closer look inside Pinterest counts as a closeup and signals creative interest. Following the destination URL off Pinterest counts as an outbound click and signals referral traffic. Track them separately because one stays on-platform while the other leaves it.

Can I get analytics for Pins I did not publish through the API?

Yes. Requesting with source set to platform and a connected accountId fetches recent Pins straight from Pinterest, so older Pins are included rather than only items created through this API.

Where can I use Pinterest analytics data?

Typical destinations include customer-facing dashboards, SaaS reporting, agency client reports, internal content scoring, and automation that reacts to strong or weak Pin performance.

Recent Pins Response
{
    "success": true,
    "total": 2,
    "page": 1,
    "limit": 10,
    "posts": [
      {
        "source": "platform",
        "postId": null,
        "content": "A short example update.",
        "publishedAt": "2026-04-12T07:28:45Z",
        "aggregated": {
          "impressions": 4,
          "reach": null,
          "likes": 0,
          "comments": 0,
          "shares": null,
          "saves": 0,
          "clicks": 1,
          "views": null,
          "engagementRate": null
        },
        "platforms": [
          {
            "platform": "pinterest",
            "platformPostId": "1143210686684505466",
            "platformPostUrl": "https://www.pinterest.com/pin/1143210686684505466/",
            "metrics": {
              "impressions": 4,
              "reach": null,
              "likes": 0,
              "comments": 0,
              "shares": null,
              "saves": 0,
              "clicks": 1,
              "views": null,
              "engagementRate": null
            }
          }
        ]
      }
    ]
}