Credits
Twitter API billing: instant X API credit top-up
Charge a saved payment method for USD 10-500 of tweet, profile, follower, monitor, webhook, export, and X write API credits. Includes response fields.
- 200
- 400
- 401
- 429
POST
Twitter API billing: instant X API credit top-up
Add X API credits for tweet, follower, monitor, webhook, export, and write calls.
Use this Twitter API billing route with an existing saved payment method.
At USD 0.00015 per credit, a USD 25 quick top-up adds 166,666 credits, rounded down to whole credits.
Only the
The request body is missing a numeric
Missing or invalid API key.
Too many requests. Wait for the
Add API credits with a saved payment method
Use quick top-up when the account already has a reusable payment method. Send a USD amount from 10 through 500. The route funds tweet, profile, follower, monitor, webhook, export, and X write requests without creating a hosted checkout page. Readoutcome before handling any other response field. charged means the
credits and new balance are ready. requires_action means the client must
complete the payment confirmation flow. Another outcome can require adding a
payment method first.
Never print or persist clientSecret. Pass it directly to the payment
confirmation flow. Log only the outcome, added credits, and resulting balance
after a successful charge.
Quick top-up differs from standard checkout status. The status route polls a
hosted checkout session by session_id. This route returns its own immediate
payment outcome for the saved payment method.
Free - does not consume credits
Headers
string
required
Your API key. Session cookie authentication is also supported.
string
required
Must be
application/json.Body
number
required
Amount in US dollars to charge. Minimum 500.
charged outcome grants credits and updates balance. If the endpoint returns requires_action, complete payment authentication with clientSecret before retrying the metered API call. Pass clientSecret to the billing confirmation flow only; do not print it in logs. If it returns no_payment_method, create a checkout top-up instead.
Response
200 Charged
Payment succeeded immediately. Credits added to your balance.string
Always
"charged".string
Updated credit balance after top-up (Bigint string).
string
Number of credits added (Bigint string).
200 Requires action
Payment requires additional authentication (e.g., 3D Secure). Use the returned client secret with the billing confirmation flow to complete the payment.string
Always
"requires_action".string
Payment client secret for completing the payment.
200 No payment method
No saved payment method on file. Redirect the user to add one via the billing portal, or use the standard top-up endpoint instead.string
Always
"no_payment_method".400 Invalid input
dollars value or includes too many decimal places.
401 Unauthenticated
429 Rate limited
Retry-After header before retrying.
Related. Top Up Credits · Get Top-Up Status · Get Credits · Billing Guide
- 200
- 400
- 401
- 429
Twitter API billing: instant X API credit top-up