Get the Pin Spacing rule for a URL

GET

/v1/accounts/{accountId}/pin-spacing/applied-rule

curl --request GET \
  --url 'https://api-v1.tailwind.ai/v1/accounts/example/pin-spacing/applied-rule?url=example' \
  --header 'Authorization: Bearer <token>'

• Production
• Development

The Pin Spacing rule the scheduler applies to Pins linking to url, resolved the same way useNextOpenSlot resolves it: a linked URL follows its base URL’s rule, a custom rule for the URL beats the account default, and URLs match regardless of http/https and trailing slashes. rule is null when no rule applies, meaning Pin Spacing does not constrain that URL. useNextOpenSlot on POST /v1/accounts/{accountId}/posts honors this rule. An explicit sendAt sets only the Pin’s initial time and is not an exemption from Pin Spacing: a later Pin Spacing respace or schedule shuffle can still move the Pin, and the API has no way to lock it in place. Read-only: rules are managed in the Tailwind dashboard.

Authorizations

• bearerAuth

Parameters

Path Parameters

accountId

required

string

Numeric Tailwind account ID returned by GET /v1/accounts

Query Parameters

url

required

string

<= 2048 characters

The Pin destination URL to resolve

Responses

200

The rule that applies to the URL, or null

Media typeapplication/json

object

data

object

url

required

The URL that was resolved, as sent

string

linkedToUrl

required

The base URL whose rule url follows when url is a linked URL; null otherwise.

string

nullable

rule

required

The applied rule, or null when Pin Spacing does not constrain the URL.

object

ruleType

required

DEFAULT is the account-wide rule; CUSTOM is set for one URL

string

Allowed values: DEFAULT CUSTOM

spacing

required

Minimum gap between Pins to the URL

integer

spacingUnits

required

string

Allowed values: DAYS

url

CUSTOM only: the URL the rule is set for

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "rule": {
      "ruleType": "DEFAULT",
      "spacingUnits": "DAYS"
    }
  }
}

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

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

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.