Get Pin analytics

GET

/v1/accounts/{accountId}/pins/{pinId}/analytics

const url = 'https://api-v1.tailwind.ai/v1/accounts/example/pins/example/analytics';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api-v1.tailwind.ai/v1/accounts/example/pins/example/analytics \
  --header 'Authorization: Bearer <token>'

One Pin’s Pinterest performance over a date window: summary totals, a per-day series, and lifetime totals that ignore the window.

pinId is the PINTEREST Pin id, not the Tailwind postId returned by the posts endpoints. A published post carries its Pinterest pinId; GET /v1/accounts/{accountId}/top-pins returns them directly. Passing a Tailwind postId here returns 404.

Only a Pin this account OWNS can be read. Pinterest itself would also report on Pins sitting on group boards this account collaborates on; this endpoint deliberately does not, because holding the account is not evidence of owning the Pin and this read does not verify board collaboration. Any other Pin id — absent, someone else’s, on a shared board, or unreadable — returns the same 404, so this endpoint cannot be used to probe which Pins exist.

Omit startDate and endDate for the last 30 days (today and the 29 days before it, UTC). Supply both to choose a window; supplying only one is a 400. The window actually used is echoed back as startDate/endDate inside data, so a caller never has to infer the period a number covers. Pinterest’s own limits apply: startDate no more than 90 days before today, endDate no more than 90 days after startDate.

Authorizations

bearerAuth

Parameters

Path Parameters

accountId

required

string

Numeric Tailwind account ID returned by GET /v1/accounts

pinId

required

string

The Pinterest Pin id — a numeric string. NOT the Tailwind postId from GET /v1/accounts/{accountId}/posts.

Query Parameters

startDate

string format: date

First day of the reporting window, as a UTC calendar date (YYYY-MM-DD). Must be supplied together with endDate; omit both for the last 30 days. Pinterest does not report further back than 90 days.

endDate

string format: date

Last day of the reporting window, inclusive, as a UTC calendar date (YYYY-MM-DD). Must be supplied together with startDate. Cannot be more than 90 days after startDate.

Responses

200

The Pin’s analytics over the resolved window

application/json

object

data

object

pinId

required

string

accountId

required

string

startDate

required

string format: date

endDate

required

string format: date

summaryMetrics

required

Pinterest metrics, camelCased (impression, save, saveRate, pinClick, outboundClick, engagement, engagementRate, …). A metric Pinterest does not report for this subject is ABSENT; a metric it reports as not-yet-computed is present and NULL. The two mean different things — absent will never arrive, null may.

object

key

additional properties

number

nullable

dailyMetrics

required

Array<object>

object

date

required

The UTC day these metrics cover

string format: date

dataStatus

Pinterest’s readiness marker for this day — READY, PROCESSING, BEFORE_PIN_CREATED and similar. Anything other than READY explains why the day’s metrics are null or zero; PROCESSING is the only one worth re-reading later.

string

metrics

required

object

key

additional properties

number

nullable

lifetimeMetrics

Totals since the Pin was created, ignoring the requested window.

object

meta

object

requestId

Unique request ID for debugging

string

Example^generated

{
  "data": {
    "pinId": "example",
    "accountId": "example",
    "startDate": "2026-04-15",
    "endDate": "2026-04-15",
    "summaryMetrics": {
      "additionalProperty": 1
    },
    "dailyMetrics": [
      {
        "date": "2026-04-15",
        "dataStatus": "example",
        "metrics": {
          "additionalProperty": 1
        }
      }
    ],
    "lifetimeMetrics": {
      "additionalProperty": 1
    }
  },
  "meta": {
    "requestId": "example"
  }
}

400

Invalid request

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body"
  },
  "meta": {
    "requestId": "abc123"
  }
}

401

Authentication required or invalid bearer credentials

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "abc123"
  }
}

403

Pinterest refused to report analytics for this subject. PERMANENT, and distinct from the collaborator-board 403 on the board endpoints: for a Pin, Pinterest has forbidden analytics on it and it will never start reporting; for an account, analytics require a Pinterest business account. Retrying will return the same answer.

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Pinterest does not permit analytics for this Pin. This is permanent for this Pin — it will not start reporting later, so do not retry.",
    "reason": "pinterest_analytics_forbidden"
  },
  "meta": {
    "requestId": "abc123"
  }
}

404

Resource not found

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Account not found"
  },
  "meta": {
    "requestId": "abc123"
  }
}

422

The account’s Pinterest connection is no longer usable. Your API key is fine — this is not an authentication failure on Tailwind’s side, which is why it is not a 401. The account holder needs to reconnect Pinterest in Tailwind before this operation can succeed.

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Reconnect your Pinterest account to manage Boards.",
    "reason": "pinterest_reconnect_required"
  },
  "meta": {
    "requestId": "abc123"
  }
}

429

Rate limit exceeded

application/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

string

resolve_url

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit of 5000 requests exceeded. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "abc123"
  }
}

Get Pin analytics

Authorizations

Parameters

Path Parameters

Query Parameters

Responses

200

Examplegenerated

400

Example

401

Example

403

Example

404

Example

422

Example

429

Example

Example^generated