---
title: "Get Pin Analytics"
method: GET
path: "/v1/pins/{pin_id}/analytics"
tags: ["Pins"]
---

# Get Pin Analytics

`GET /v1/pins/{pin_id}/analytics`

## Request

- Base URL: `https://api.pinbridge.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pinbridge.io/v1/pins/{pin_id}/analytics`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Pin-level analytics (impressions, saves, clicks, outbound clicks) over a date range.

PinBridge copies every published pin's analytics nightly, so most reads are
answered from that stored history (`source: stored` in the response, with
`data_as_of`) without calling Pinterest. Live ranges are capped at 90 days,
stored ranges at 366. Sandbox-simulated pins return zeroed metrics.

A pin deleted on Pinterest (`removed_from_pinterest_at` set) is answered
from the stored history. Without stored history it fails with `409
pin_removed_on_pinterest`, which is also what a live read returns when
Pinterest no longer has the pin.

## Path parameters

- `pin_id` string, uuid, required

## Query parameters

- `start_date` string, date, nullable: Inclusive start (YYYY-MM-DD); default 30 days ago
- `end_date` string, date, nullable: Inclusive end (YYYY-MM-DD); default today
- `metrics` string, nullable: Comma-separated Pinterest metric types, e.g. IMPRESSION,SAVE,PIN_CLICK,OUTBOUND_CLICK. Defaults to the organic engagement set.
- `source` 'auto' | 'stored' | 'live': auto (default): PinBridge's stored history when it covers the range, else Pinterest. stored: stored history only (up to 366 days, beyond Pinterest's 90). live: always ask Pinterest (counts against the read limit).
- `include_daily` boolean: false: return only the range totals, with an empty daily list. Use it when the totals are all you need, e.g. over 90 days.

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Response `200`

Successful Response

- PinAnalyticsResponse: Normalized Pinterest analytics for one pin.
  - `pin_id` string, uuid, required
  - `pinterest_pin_id` string, nullable, required
  - `account_id` string, uuid, required
  - `start_date` string, required
  - `end_date` string, required
  - `provider_mode` 'pinterest' | 'simulated', required
  - `totals` object, required: Each metric summed over the range, lowercase metric names. total_comments and total_reactions are lifetime counts on live reads and 0 on stored reads, which do not keep them; Pinterest does not report them per day.
  - `daily` AnalyticsDailyMetric[], required: One entry per day in the range; empty when include_daily=false
    - `date` string, required
    - `data_status` string, nullable
    - `metrics` object, required
  - `removed_from_pinterest_at` string, date-time, nullable: Set when the pin no longer exists on Pinterest; the numbers then come from PinBridge's stored history
  - `source` 'live' | 'stored' | 'simulated': Where the numbers came from: live (Pinterest, just now), stored (PinBridge's nightly copy), or simulated (sandbox)
  - `data_as_of` string, date-time, nullable: For stored reads: when PinBridge last fetched this account's analytics
  - `history_start` string, nullable: For stored reads: earliest day PinBridge has stored for this account

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/pinbridge/apis/pinbridge-api.md) · [All operations](https://skmtc.dev/pinbridge/apis/pinbridge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pinbridge/apis/pinbridge-api/revisions/b17603589d01?raw)