Get schedule

GET

/v1/accounts/{accountId}/schedule

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

The account’s schedule over a date window, as dated entries: which smart schedule slots are open, and what occupies the rest. The companion read to GET /v1/accounts/{accountId}/timeslots, which returns the recurring weekly rules and says nothing about occupancy.

Entries are ordered earliest first. open marks an unused smart schedule slot; scheduled, publishing and published each name the Pin holding that time. timeslotId is absent on a Pin that sits on no slot at all — scheduled at an arbitrary time, or left behind by a slot that has since moved.

This is a read, not a placement primitive: a slot that is open here can be taken before a subsequent write lands. To put a Pin on the schedule, use useNextOpenSlot on the create or schedule endpoints, which resolves and claims a slot under the account’s schedule lock — do not copy a time from this response into sendAt.

Authorizations

bearerAuth

Parameters

Path Parameters

accountId

required

string

Numeric Tailwind account ID returned by GET /v1/accounts

Query Parameters

from

string format: date-time

Start of the window (ISO 8601). Defaults to now.

string format: date-time

End of the window (ISO 8601). Defaults to 14 days after the start, and cannot be more than 60 days after it.

Responses

200

The account’s schedule over the requested window

application/json

object

data

object

schedule

Array<object>

One dated occurrence on the account’s schedule. Either an open smart schedule slot, or the Pin holding that time.

object

sendAt

When this entry falls (Unix timestamp, seconds)

integer

state

Open = an unused smart schedule slot; scheduled = a queued Pin; publishing = a Pin mid-publish; published = already on Pinterest

string

Allowed values: open scheduled publishing published

timeslotId

The smart schedule slot this entry sits on. Absent for a Pin scheduled off-slot.

string

post

The Pin holding this time. Absent when state is open.

object

postId

string

title

string

url

string

boardId

string

window

The window actually read, as Unix timestamps.

object

from

integer

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "schedule": [
      {
        "state": "open"
      }
    ]
  }
}

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

404

Resource not found

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": "NOT_FOUND",
    "message": "Account not found"
  },
  "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"
  }
}

503

Timed out building the schedule. Nothing is wrong with the request; retry, or ask for a shorter window.