Skip to content
Tailwind API

List the Pins on a board

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

The Pins saved on one of the account’s boards, secret boards included, in Pinterest’s board order: mostly newest first, but not strictly. Each Pin carries its Pinterest URL, image URL, destination link, saved time and, when it sits in a section, the section’s id. This lists what is on the board now on Pinterest, however each Pin got there, unlike GET /v1/accounts/{accountId}/posts, which lists only Tailwind’s own post records.

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, which for a save is when it was saved, and either may be given alone. Because board order is not strictly by date, every Pin is checked and the walk does not stop early: a response can hold fewer than limit Pins, or none, while cursor is still present. Keep paging until cursor is absent: only then has the whole board been read. To sort by date, sort the collected Pins by createdAt.

Reading a board 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

boardId
required
string

Numeric Pinterest board ID returned by GET /v1/accounts/{accountId}/boards. Tailwind’s own b_-prefixed CSV export format is accepted and normalized; board names and board URLs are rejected with a 400.

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 or saved 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 or saved at or before this instant (ISO 8601 date-time in UTC, e.g. 2026-10-07T23:59:59Z)

Responses

Section titled “Responses”

200

Section titled “200”

One page of the board’s Pins, in board order

Media typeapplication/json
object
data
object
accountId
required
string
boardId
required
string
pins
required
Array

One Pin saved on a board.

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
boardSectionId
required

The board section the Pin sits in, the same id GET /v1/accounts/{accountId}/boards/{boardId}/sections returns. Null when the Pin sits on the board itself.

string
nullable
cursor

Pass back as cursor for the next page. Absent once the whole board has been read.

string
meta
object
requestId

Unique request ID for debugging

string
Examplegenerated
{
  "data": {
    "accountId": "example",
    "boardId": "example",
    "pins": [
      {
        "pinId": "example",
        "boardId": "example",
        "title": "example",
        "description": "example",
        "destinationUrl": "example",
        "pinUrl": "example",
        "imageUrl": "example",
        "createdAt": "2026-04-15T12:00:00Z",
        "isRepin": true,
        "creativeType": "example",
        "boardSectionId": "example"
      }
    ],
    "cursor": "example"
  },
  "meta": {
    "requestId": "example"
  }
}

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

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.

502

Section titled “502”

Pinterest failed the request with an error of its own. A create may still have taken effect, so list Boards or sections before repeating one; other requests can be retried. If the same request keeps failing, Pinterest is refusing it rather than having an outage.

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_GATEWAY",
    "message": "Pinterest couldn't complete this request. Please try again.",
    "reason": "pinterest_request_failed"
  },
  "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.