List saved keywords
const url = 'https://api-v1.tailwind.ai/v1/keywords?limit=50';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/keywords?limit=50' \ --header 'Authorization: Bearer <token>'The authenticated organization’s saved keywords, newest first. This is the same list the Tailwind dashboard’s Saved Keywords page shows — it is not keyword research; these are terms the organization has already chosen to track.
Pass url to read only the keywords saved for one destination URL, for example to check what a Pin’s link already has before saving more. search and url cannot be combined; a request with both returns 400.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Only return keywords containing this text. Cannot be combined with url.
Only return keywords associated with this destination URL. Must be a full http or https URL. It is matched exactly against the URL the keyword was saved with, trailing slash and query string included, except that http and https are treated as the same. A bare domain such as https://example.com also matches keywords saved for any page on that domain. Cannot be combined with search.
Keywords per page.
Opaque cursor from a previous response’s pagination.nextCursor.
Responses
Section titled “Responses”A page of saved keywords
object
object
A keyword on the organization’s saved list — the same list the Tailwind dashboard’s Saved Keywords page shows.
object
Saved keyword ID
The keyword text
When the keyword was added to the list
URLs of the organization’s own that this keyword is associated with
Tags the organization has applied to this keyword
object
Estimated monthly Pinterest search volume. Absent when Tailwind has no volume data for the term; treat a missing value as unknown, not as zero demand.
How strongly the term signals buying intent. Absent when Tailwind has no interest data for it.
Language detected for the term, e.g. “english”. Absent when Tailwind has no interest data for it.
object
Pass as cursor to fetch the next page
Total matching keywords across all pages
object
Unique request ID for debugging
Examplegenerated
{ "data": { "keywords": [ { "id": "example", "term": "example", "savedAt": "2026-04-15T12:00:00Z", "urls": [ "example" ], "tags": [ { "id": "example", "name": "example" } ], "pinterestSearchVolume": 1, "commercialIntentScore": 1, "detectedLanguage": "example" } ], "pagination": { "limit": 1, "hasMore": true, "nextCursor": "example", "totalCount": 1 } }, "meta": { "requestId": "example" }}Invalid request
object
object
Error code
Error message
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.
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.
object
Unique request ID for debugging
Example
{ "error": { "code": "BAD_REQUEST", "message": "Invalid request body" }, "meta": { "requestId": "abc123" }}Authentication required or invalid bearer credentials
object
object
Error code
Error message
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.
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.
object
Unique request ID for debugging
Example
{ "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }, "meta": { "requestId": "abc123" }}Rate limit exceeded
object
object
Error code
Error message
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.
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.
object
Unique request ID for debugging
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”Seconds until the daily limit resets at midnight UTC.