Get bulk create status

GET

/v1/post-batches/{batchId}

curl --request GET \
  --url https://api-v1.tailwind.ai/v1/post-batches/example \
  --header 'Authorization: Bearer <token>'

• Production
• Development

Poll a batch started by POST /v1/accounts/{accountId}/post-batches. Every entry is reported in request order as created (with its postId), failed (with the error a single create would have returned) or pending. The batch is completed once no entry is pending. Poll every ~10 seconds. To retry, resend only the failed entries in a new batch; an entry that failed with a note that the Pin may exist should be checked with GET /v1/accounts/{accountId}/posts first.

Authorizations

• bearerAuth

Parameters

Path Parameters

batchId

required

string

Batch ID returned by POST /v1/accounts/{accountId}/post-batches

Responses

200

Batch status

Media typeapplication/json

object

data

object

batch

object

id

string

accountId

string

status

string

Allowed values: queued processing completed

createdAt

string format: date-time

completedAt

string format: date-time

summary

object

total

integer

created

integer

failed

integer

pending

integer

results

One entry per submitted post, in request order.

Array<object>

object

index

Position of the entry in the submitted posts array.

integer

status

string

Allowed values: created failed pending

postId

Present when created.

string

postStatus

The new post’s status when created: draft or queued.

string

error

Present when failed: the error a single create would have returned.

object

code

string

message

string

reason

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "batch": {
      "status": "queued",
      "results": [
        {
          "status": "created"
        }
      ]
    }
  }
}

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.