Skip to main content
PATCH
Twitter profile update API: name, bio, location, URL
Use this Twitter profile update API for public profile text. Change a display name, bio, location, or website in one request. Send only the fields that need new values. Omitted fields remain unchanged. The connected account receives every approved change. This route does not change a username, avatar, banner, or birth date. Use Update Avatar or Update Banner for profile images. Read X’s profile customization guide before updating profile text.

Update Twitter profile text

Call PATCH /x/profile to update Twitter profile fields programmatically. Provide the connected account plus at least one supported field. The name field changes the display name, not the @username. The description field changes the public bio. The location and url fields change their matching public labels.
10 credits per call · All plans from $0.00012/credit

Review every profile field

Review the exact display name, bio, location, and website before approval. Names allow 1 to 50 characters. Bios allow 160 characters. Locations allow 30 characters. Website values must be valid URLs. Empty description or location values clear those fields. An empty name or invalid URL returns 400. Keep API keys and private notes outside public profiles.

Automate a safe profile update

Create one idempotency key for each account and field set. Reuse that key after a network interruption. Workers handling the same update must share it. Change the key after editing any value. A 200 response is terminal. Poll statusUrl after 202 until terminal becomes true.

Coordinate updates across connected accounts

Send one approved request for each connected X account. Give every request a key for its exact account and field set. Wait for an account’s terminal result before starting its next profile change. Other accounts may update in parallel with different keys. Store the account, requested fields, request hash, write action ID, and status. Workers use this record to avoid duplicate profile updates. It also shows which display name, bio, location, or website each action changed. Give different teams their own API keys. Never share credentials between unrelated profile workflows.

Verify the saved Twitter profile

After a terminal write, use Twitter Profile Lookup. Compare its name, description, location, and website with the approved request. This check works across user profiles, including user-owned brand accounts. Profile updates never change posts, tweets, followers, replies, likes, or lists. For a campaign, save earlier values and restore them with a new key. Store the earlier and replacement values with the action ID. Apply the replacement at launch, then verify the public profile. Restore earlier fields with a new idempotency key after the campaign. This history makes each temporary Twitter profile update reversible. Treat the write action as lifecycle evidence. Treat the later profile lookup as public proof. Save both timestamps when profile changes need an audit trail. Never store authentication tokens with those public profile values.

Fix Twitter profile update failures

Fix rejected 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. Honor Retry-After after 429. Check safeToRetry after 500 or 503. Delete fake verification marks or unsafe profile links, then retry. X documents more causes in its profile save troubleshooting guide. Do not create a new action after an uncertain network response. Check the saved statusUrl before creating another action. The same request may reuse its original idempotency key. Change the key after correcting any field. Retry a server error only when safeToRetry allows it.

Twitter API update profile questions

What endpoint changes a Twitter display name or bio?

Send name or description to PATCH /x/profile. The name field changes the display name, not the @username. An empty description clears the bio.

Can I automate recurring Twitter bio changes?

Yes. Approve every replacement value. Use a new key for each scheduled change. Check the action and public profile. Keep the earlier bio for rollback.

Can this Twitter API change an account username?

No. The name field changes only the public display name. It never changes the @username or numeric account ID. Keep username changes outside this workflow.

Does a profile update change tweets or follower counts?

No. Existing tweets, replies, followers, following, likes, lists, and communities stay unchanged. A later profile lookup may return those counts, but this route cannot edit them.

Can this endpoint update a profile picture or banner?

No. Use the dedicated avatar or banner route. Those endpoints validate image type and size separately.

Which authentication works with this Twitter API route?

Use an x-api-key header or an OAuth bearer token. The chosen connected X account supplies the profile identity. Generated SDKs can send the same fields and headers.

How should I schedule temporary profile changes?

Check both values before adding them to the schedule. Use one key for the launch action and a different key for the rollback. Poll each action until terminal, then verify the public profile before continuing.

Headers

string
required
Your API key. OAuth bearer authentication is also supported. Generate a key from the dashboard.
string
required
Unique key for this intended write. Reuse it only for an exact network replay.
string
required
Must be application/json.

Body

string
required
X username or account ID of your connected account to act as.
string
Display name. Maximum 50 characters.
string
Profile bio. Maximum 160 characters.
string
Profile location. Maximum 30 characters.
string
Website URL. Must be a valid URL.

Response

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

Durable write recovery

Send one unique Idempotency-Key per intended write. Reuse it only for the same account, target, payload, and media.
  1. Store id, the nested hash in request, billing, and statusUrl.
  2. Poll after Retry-After or pollAfterMs when terminal is false.
  3. Trust safeToRetry and nextAction before any new write.

200 Terminal or 202 active

Store terminal results. Poll active actions without creating another write.
  • 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. Preserve the same key.
  • After HTTP 500, retry only when safeToRetry is true.
  • After HTTP 503, poll while terminal is false.
See Get Write Action Status for every lifecycle field, terminal state, billing field, and retry rule.