Skip to content
Tailwind API

List every Pin on the account

GET
/v1/accounts/{accountId}/pins
curl --request GET \
  --url 'https://api-v1.tailwind.ai/v1/accounts/example/pins?limit=100&pinType=ALL' \
  --header 'Authorization: Bearer <token>'

Every Pin on the connected Pinterest account, newest first, however it was published: through Tailwind, directly on Pinterest, or by another tool. This is the complete inventory, unlike GET /v1/accounts/{accountId}/posts, which lists only Tailwind’s own post records, and GET /v1/accounts/{accountId}/top-pins, which returns a ranked subset. Pins on secret boards are included.

Each Pin’s pinId is the Pinterest Pin id, which GET /v1/accounts/{accountId}/pins/{pinId}/analytics takes. It is not a Tailwind postId.

startDate and endDate filter on when the Pin was created (or saved, for a repin), and either may be given alone. Pinterest itself has no date filter, so pages newer than endDate are read and skipped server-side; a response can therefore hold fewer than limit Pins, or none, while cursor is still present. Keep paging until cursor is absent: only then is the inventory complete. pinType ORIGINAL keeps Pins the account created, SAVED keeps saves of other people’s Pins. A save of the account’s own Pin to another board (isRepin true) is in neither, so ORIGINAL and SAVED can sum to less than ALL: to count every save, use ALL and isRepin.

Reading the inventory is free and consumes no credits.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
accountId
required
string

Numeric Tailwind account ID returned by GET /v1/accounts

Query Parameters

Section titled “Query Parameters”
cursor
string

Pagination cursor from the previous response

limit
integer
default: 100 >= 1 <= 250

Pins to read from Pinterest per page, 1 to 250. Defaults to 100.

startDate
string format: date-time

Only Pins created at or after this instant (ISO 8601 date-time in UTC, e.g. 2026-10-01T00:00:00Z)

endDate
string format: date-time

Only Pins created at or before this instant (ISO 8601 date-time in UTC, e.g. 2026-10-07T23:59:59Z)

pinType
string
default: ALL
Allowed values: ALL ORIGINAL SAVED

ORIGINAL for Pins the account created (isRepin false), SAVED for saves of other people’s Pins, ALL for everything. Defaults to ALL. A save of the account’s own Pin to another board is in neither ORIGINAL nor SAVED, so the two can sum to less than ALL.

Responses

Section titled “Responses”

200

Section titled “200”

One page of the account’s Pins, newest first

Media typeapplication/json
object
data
object
accountId
required
string
pinType
required
string
Allowed values: ALL ORIGINAL SAVED
pins
required
Array<object>

One Pin on the account, however it was published.

object
pinId
required

The Pinterest Pin id. This is the id GET /v1/accounts/{accountId}/pins/{pinId}/analytics takes, not a Tailwind postId.

string
boardId
required

The Pinterest board the Pin is saved to, the same id GET /v1/accounts/{accountId}/boards returns

string
title
string
description
string
destinationUrl

Where the Pin links to, verbatim, including any UTM parameters

string
pinUrl

The Pin’s own page on Pinterest

string
imageUrl
string
createdAt
required

When the Pin was created, or saved for a repin

string format: date-time
isRepin
required

True when the Pin was saved from another Pin, including the account’s own Pins saved to another board

boolean
creativeType
required

Pinterest’s creative format for the Pin, verbatim, for example REGULAR, VIDEO, CAROUSEL, IDEA or SHOPPING. Pinterest adds values over time, so treat it as an open set. Null when Pinterest did not report one.

string
nullable
cursor

Pass back as cursor for the next page. Absent once the inventory, or the requested window, is exhausted.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "data": {
    "pinType": "ALL"
  }
}

400

Section titled “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

Section titled “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

Section titled “403”

Pinterest refused to list this account’s Pins (reason pinterest_forbidden). Permanent: retrying returns 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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "reason": "example",
    "resolve_url": "example"
  },
  "meta": {
    "requestId": "example"
  }
}

404

Section titled “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

Section titled “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

Section titled “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

Section titled “Headers”
Retry-After
integer

Seconds until the daily limit resets at midnight UTC.

500

Section titled “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

Section titled “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

Section titled “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.