Skip to main content
PATCH https://xquik.com/api/v1/x/profile/banner This route updates one connected account’s header image. Upload a JPEG or PNG file, or provide a fetchable HTTPS image URL. The maximum file size is 95 MiB. Xquik shrinks larger files under 2 MB for X. X recommends 1500 × 500 pixels for profile banners.

Update a Twitter profile banner through the API

Call PATCH /x/profile/banner to replace the wide header image. Use Update Avatar for the profile picture. Use Update Profile for names and other public text fields. This route never retrieves another user’s banner.
10 credits per call · All plans from $0.00012/creditA write that must sign in to your X account first adds 10 credits. Xquik refunds them if the sign-in fails. A sign-in that works keeps them, even if X then refuses the write. See the X sign-in fee.

Prepare Twitter profile banner dimensions

Use a 1500 × 500 pixel canvas. That size has a 3:1 aspect ratio and matches X’s recommended header dimensions. Xquik resizes images outside 200x100 to 8192x8192 pixels. Accept only JPEG or PNG images. This route does not support animated GIFs. Review every export before uploading. Read X’s profile banner guidance for current layout recommendations. Preview the banner on desktop and a mobile device. The profile picture can cover the bottom left corner. Keep faces, logos, and text outside that area. Other sizes or crops can hide parts of the artwork. Check the image size before queueing the write. Keep one 1500 × 500 source file for each approved campaign. Export banner images from that source. Do not resize previous uploads. Record the dimensions and final file size with the source. Use approved logos and colors. A banner change does not prove higher engagement. Measure profile visits and follows separately.

Automate a Twitter banner update

Create one idempotency key for the selected account and banner. Reuse it only after an exact network interruption. Generate a new key after changing the image or account. A 200 response is terminal. Poll statusUrl after 202 until terminal becomes true.

Verify the updated Twitter banner

After a terminal write, use Twitter Profile Lookup. Open its profileBannerUrl value. Compare the rendered header with the approved source. Check desktop and mobile crops. Store the action ID and verification timestamp.

Fix X (Twitter) profile banner API errors

Fix invalid image fields after 400. Replace authentication after 401. Add credits after 402. Reconnect after 403. Connect a missing account after 404. Keep the original action after 409. Replace rejected media after 422. Honor Retry-After after 429. Check safeToRetry after 500 or 503.

Headers

Body

Response

Connect the requested account, then submit a newly approved write.

Durable write recovery

Send one unique Idempotency-Key per intended write. Replay the same account, target, payload, and media after a lost response. Keep the original key for that replay.
  1. Store id, the nested hash in request, billing, and statusUrl.
  2. Poll after Retry-After or pollAfterMs when terminal is false.
  3. Retry only when safeToRetry is true.
  4. Use a new key when nextAction.requiresNewIdempotencyKey is true.

200 terminal or 202 active

  • After HTTP 200, store the result and settled billing.
  • After HTTP 202, poll the same action. Never submit another write.
  • After HTTP 400, fix the named field. Use a new idempotency key.
  • After HTTP 401, fix authentication. Do not retry unchanged.
  • After HTTP 402, fund the account before another write.
  • After HTTP 403, reconnect the account.
  • After HTTP 409, keep the original action. Use a new key for new input.
  • After HTTP 422, fix the rejected request before retrying.
  • After HTTP 429, wait for Retry-After. Follow nextAction.
See Get Write Action Status for every lifecycle field and terminal state. That page also lists every billing field and retry rule.

Response examples

200 example

202 example

  • 400 { "error": "missing_idempotency_key", "message": "Idempotency-Key is required. Generate one unique key for this write.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true }
  • 401 { "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }
  • 402 { "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }
  • 403 { "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }
  • 404 { "error": "account_not_found", "message": "X account not found. Connect it first at /dashboard/x-accounts." }
  • 409 { "error": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true }
  • 413 { "error": "media_too_large", "message": "This image stays over X's size limit after shrinking. Send a smaller one." }
  • 415 { "error": "unsupported_media_type", "message": "Xquik couldn't read this image. Send a valid image file." }
  • 422 { "error": "x_rejected", "message": "X rejected this request. Check what you sent & the account on x.com before you try again." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 500 { "error": "x_write_failed", "message": "Write action failed unexpectedly. Contact support if this persists." }
  • 503 { "error": "write_tracking_unavailable", "message": "Write tracking unavailable. Try again.", "charged": false, "chargedCredits": "0", "retryable": true, "safeToRetry": true }