Pins

Get Pin Analytics

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.

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

Path parameters

pin_idstring uuid required

Query parameters

start_datestring date nullable

Inclusive start (YYYY-MM-DD); default 30 days ago

end_datestring date nullable

Inclusive end (YYYY-MM-DD); default today

metricsstring 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_dailyboolean

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-keystring nullable
authorizationstring nullable

Response

Successful Response

pin_idstring uuid required
pinterest_pin_idstring nullable required
account_idstring uuid required
start_datestring required
end_datestring required
provider_mode'pinterest' | 'simulated' required
totalsobject 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.

removed_from_pinterest_atstring 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_ofstring date-time nullable

For stored reads: when PinBridge last fetched this account's analytics

history_startstring nullable

For stored reads: earliest day PinBridge has stored for this account

Changes

No recorded changes to this operation across all 1 revision of this API.