Get account analytics

GET

/v1/accounts/{accountId}/analytics

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

• Production
• Development

Pinterest performance for the whole account over a date window: summary totals plus a per-day series. The same numbers Pinterest Insights shows in the Tailwind dashboard, covering claimed and unclaimed content alike. Totals combine paid (promoted) and organic activity unless contentType says otherwise: ORGANIC reports unpromoted activity only, PAID promoted only. The per-Pin analytics endpoint is always organic-only, so its figures compare against ORGANIC totals, not the default blend. The filter actually applied is echoed back as contentType.

This is the account-wide rollup. For one Pin use GET /v1/accounts/{accountId}/pins/{pinId}/analytics; for the best performers use GET /v1/accounts/{accountId}/top-pins.

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

Query Parameters

contentType

string

default: ALL

Allowed values: ALL PAID ORGANIC

Which activity to count: ORGANIC for unpromoted activity only, PAID for promoted (ad) activity only, ALL for both blended. Defaults to ALL.

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

Account analytics over the resolved window

Media typeapplication/json

object

data

object

accountId

required

string

startDate

required

string format: date

endDate

required

string format: date

contentType

required

string

Allowed values: ALL PAID ORGANIC

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

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

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "contentType": "ALL"
  }
}

400

Invalid request

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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": "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.

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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": "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

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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": "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.

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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": "UNPROCESSABLE_ENTITY",
    "message": "Reconnect your Pinterest account to manage Boards.",
    "reason": "pinterest_reconnect_required"
  },
  "meta": {
    "requestId": "abc123"
  }
}

429

Rate limit exceeded

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit of 10000 requests for this organization exceeded. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "abc123"
  }
}

Headers

Retry-After

integer

Seconds until the daily limit resets at midnight UTC.

500

Pinterest failed the read with an error on its side. Whether it is permanent is unknown, so this stays a 500, but retrying right away will not help; try again later.

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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": "INTERNAL_ERROR",
    "message": "Pinterest failed to return analytics for this Pin. The error is on Pinterest's side, so retrying right away will not help. Try again later.",
    "reason": "pinterest_upstream_error"
  },
  "meta": {
    "requestId": "abc123"
  }
}

503

Pinterest rate-limited the request. Pinterest refused it before acting, so nothing was changed. Distinct from a 429, which means the organization’s shared daily request limit — retry this request in a few minutes rather than backing off across the API.

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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": "SERVICE_UNAVAILABLE",
    "message": "Pinterest is limiting requests for this account right now. Nothing was changed. Retry in a few minutes.",
    "reason": "pinterest_rate_limited"
  },
  "meta": {
    "requestId": "abc123"
  }
}

Headers

Retry-After

integer

Seconds until Pinterest’s limit for this account resets. Sent by the analytics and Pin inventory operations when Pinterest reports it; absent otherwise.