List public group boards for a keyword

GET

/v1/group-boards

const url = 'https://api-v1.tailwind.ai/v1/group-boards?keyword=example';
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/group-boards?keyword=example' \
  --header 'Authorization: Bearer <token>'

Public Pinterest group boards matching a keyword, from Tailwind’s Group Board Finder scrape cache. This is public benchmark context, not the authenticated user’s own boards — use list-boards for those.

Results are cached and refreshed in the background, so the response carries a status: ready means the data below is what we have (including an empty list, when a completed search found no group boards), warming means a search is running and no results are cached yet, and unavailable means the most recent search failed. On warming, retry after retryAfterSeconds.

Authorizations

bearerAuth

Parameters

Query Parameters

keyword

required

string

<= 100 characters

Search keyword. Trimmed, whitespace-collapsed and lowercased before lookup; 100 characters maximum.

Responses

200

Group boards for the keyword, with the scrape status

application/json

object

data

object

keyword

The normalized keyword the results are keyed on

string

status

State of the underlying scrape for this keyword

string

Allowed values: warming ready unavailable

boards

Array<object>

A public Pinterest group board from the Group Board Finder scrape cache. Not one of the authenticated user’s own boards, and not usable as a boardId when scheduling.

object

boardId

Pinterest board ID

string

name

Board name

string

description

Board description

string

url

Board URL on Pinterest

string

ownerUsername

Pinterest username of the board owner

string

imageUrl

Board cover image URL

string

pinCount

Pins on the board when last scraped

integer

followerCount

Followers of the board owner when last scraped

integer

isCollaborative

Whether the board accepts collaborators

boolean

isJoinable

Whether the board was open to join

boolean

pinThumbnailUrls

Up to four example Pin thumbnails from the board

Array<string>

lastCompletedAt

When a search for this keyword last completed successfully

string format: date-time

retryAfterSeconds

On warming, how long to wait before asking again

integer

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "status": "warming"
  }
}

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

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