Credits
Check X API Credit Top-up Payment Status API
Poll a credit checkout session for pending, paid, expired, or failed status before starting tweet, follower, monitor, or write requests. See examples.
- 200
- 400
- 401
- 404
- 429
GET
Check X API Credit Top-up Payment Status API
Free - does not consume credits
Gate Queued API Work on the Checkout Result
Store the checkout session ID when creating a standard top-up. Associate it with the intended tweet, follower, reply, monitor, or write workload. Never substitute a session from another account or purchase. Poll this endpoint before releasing credit-dependent work. Interpret the returned status as a state machine:processingkeeps the workload paused.paidallows a fresh credit-balance check.failedrequires a new checkout.expiredrequires a new checkout.
amount_dollars or credits alone. Only paid
confirms that credits were granted. Then call
Get Credits. Compare the balance with the planned
request cost.
Keep processing polls bounded. Wait between requests and honor
Retry-After after rate limiting. Several rapid polls cannot accelerate the
payment result.
Store the last observed status and check time with the session ID. This lets
another worker resume polling without creating a second purchase.
Handle terminal states explicitly. A failed or expired checkout must not be
retried as though payment were still processing. Create a new checkout only
after the user or approved billing workflow requests it.
When paid appears, release only the workload tied to that checkout. Keep
unrelated queues behind their own credit and approval checks. This prevents
one top-up from silently authorizing broader activity.
Headers
string
required
Your API key. Session cookie authentication is also supported.
Query parameters
string
required
Checkout session ID for the top-up checkout.
Response
200 Paid
Payment succeeded. Credits have been added to the account.string
Always
"paid".integer
Dollar amount requested for the top-up.
string
Credit amount granted as a Bigint string.
200 Processing
Payment has not reached a final state yet. Poll again later.string
Always
"processing".integer
Dollar amount requested for the top-up, when available.
string
Pending credit amount as a Bigint string, when available.
200 Failed
Payment failed. Create a new top-up checkout before retrying payment.string
Always
"failed".200 Expired
The checkout session expired before payment completed.string
Always
"expired".400 Invalid input
session_id query parameter is missing.
401 Unauthenticated
404 Not found
429 Rate Limited
Retry-After header before retrying.
Related: Top Up Credits · Quick Top-Up · Get Credits · Billing Guide
- 200
- 400
- 401
- 404
- 429
Check X API Credit Top-up Payment Status API