Skip to content
Tailwind API

Get credit and post usage

GET
/v1/accounts/{accountId}/usage
curl --request GET \
  --url https://api-v1.tailwind.ai/v1/accounts/example/usage \
  --header 'Authorization: Bearer <token>'

How much a Pinterest account can still spend before a credit- or post-consuming action, and when it refills. Works the same on every billing system; read billingSystem and scope to interpret the numbers. Free: this read spends nothing.

When unlimitedScheduling is true (the modular winback plan), scheduling Pins spends no credits, whatever the credit balance says. On modular billing, credits belong to this account and pay for scheduling (one credit per Pin, unless unlimitedScheduling is true) as well as AI generation; there is no post allowance, so postLimit is null. On legacy and Shopify billing, scope is organization: one credit pool and one post allowance are shared by every account in the org, so each account reports the same numbers. That pool pays for credit-priced features such as AI generation (including SmartPins from a connected feed) and Turbo, while ordinary scheduling spends the post allowance instead of credits.

This is a snapshot for planning, not an authorization. Trial allowances on modular billing are tracked separately, so zero credits does not mean nothing can be done and a positive balance does not guarantee every action. Concurrent spends can also change the numbers before your next call.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
accountId
required
string

Numeric Tailwind account ID returned by GET /v1/accounts

Responses

Section titled “Responses”

200

Section titled “200”

Credit and post usage

Media typeapplication/json
object
data

Credit and post usage for a Pinterest account, normalized across billing systems.

object
billingSystem
required

Which billing system the owning organization is on.

string
Allowed values: legacy modular shopify
scope
required

Who every value in this response belongs to. organization: one pool shared by all the org’s accounts, reported identically on each, so never add them up across accounts. account: this account alone.

string
Allowed values: organization account
credits
required
object
remaining
required

Credits available to spend now: unused monthly allowance plus purchased (modular) or bonus (legacy) credits.

integer
monthlyAllowance
required

Credits the plan grants each month.

integer
resetsAt
required

Unix timestamp the monthly allowance next refills. Null when there is no monthly allowance or no reliable upcoming reset is known.

integer
nullable
postLimit
required

The post allowance ordinary scheduling spends on legacy and Shopify billing, for the current usage period only. Null when the billing system does not meter posts (modular).

object
limit
required

Posts allowed in the current usage period. Null means unlimited.

integer
nullable
used
required

Published plus scheduled posts in the current usage period, across every Pinterest, Instagram and Facebook account in the organization.

integer
periodEndsAt
required

Unix timestamp the current usage period ends.

integer
unlimitedScheduling
required

True when the account is on the modular winback plan, which schedules Pins without spending credits while reporting zero monthly credits. Credits still pay for AI generation. Always false on legacy and Shopify billing: there, read postLimit, which covers the current usage period only.

boolean
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "data": {
    "billingSystem": "legacy",
    "scope": "organization"
  }
}

400

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Headers”
Retry-After
integer

Seconds until the daily limit resets at midnight UTC.