> ## Documentation Index
> Fetch the complete documentation index at: https://docs.privy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Refresh Twitter account

> Refresh the cached profile data for a user's linked Twitter account, including their username, display name, and profile picture.

<RequestExample>
  ```sh theme={"system"}
  curl --request POST \
    --url https://api.privy.io/v1/users/twitter/refresh \
    --header 'Authorization: Basic <encoded-value>' \
    --header 'Content-Type: application/json' \
    --header 'privy-app-id: <privy-app-id>' \
    --data '{
    "subject": "1234567890987654321"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "type": "twitter_oauth",
    "subject": "1234567890987654321",
    "username": "new_handle",
    "name": "Updated Name",
    "profile_picture_url": "https://pbs.twimg.com/profile_images/.../avatar.jpg",
    "verified_at": 1755000000,
    "first_verified_at": 1755000000,
    "latest_verified_at": 1755000000
  }
  ```

  ```json 404 theme={"system"}
  {
    "error": "No Twitter account found with the provided subject for this app"
  }
  ```

  ```json 429 theme={"system"}
  {
    "error": "Twitter account refreshes are limited to once per day",
    "code": "too_many_requests"
  }
  ```
</ResponseExample>

Privy refreshes a user's Twitter profile data whenever they log in or re-authorize their Twitter account. Use this endpoint to refresh that data for users with an existing session, who will not re-authenticate soon.

Privy only overwrites a field when Twitter returns a value for it. If Twitter omits `username`, `name`, or `profile_picture_url`, the existing value on the linked account is preserved rather than set to `null`.

### Body

<ParamField body="subject" type="string" required>
  The Twitter user ID of the account to refresh, as stored on the `subject` field of the user's
  `twitter_oauth` linked account. This is Twitter's stable numeric identifier for the account, not
  the account's username.
</ParamField>

### Returns

The refreshed `twitter_oauth` linked account. This endpoint does not return the full user object.

<ResponseField name="type" type="string" required>
  Available options: `twitter_oauth`
</ResponseField>

<ResponseField name="subject" type="string" required>
  The Twitter user ID of the account. This value is stable and does not change when the user changes
  their username.
</ResponseField>

<ResponseField name="username" type="string | null" required>
  The user's Twitter username.
</ResponseField>

<ResponseField name="name" type="string | null" required>
  The user's display name on Twitter.
</ResponseField>

<ResponseField name="profile_picture_url" type="string | null" required>
  A URL for the user's Twitter profile picture.
</ResponseField>

<ResponseField name="verified_at" type="number" required>
  Unix timestamp, in seconds, of when the user linked their Twitter account to their Privy account.
</ResponseField>

<ResponseField name="first_verified_at" type="number | null" required>
  Unix timestamp, in seconds, of when the user first linked their Twitter account.
</ResponseField>

<ResponseField name="latest_verified_at" type="number | null" required>
  Unix timestamp, in seconds, of when the user most recently linked their Twitter account.
</ResponseField>

### Errors

Two distinct conditions share each of the `404` and `429` statuses. Your app should branch on the
`error` message, not the status alone. None of these responses include a `Retry-After` header.

| Status | Error                                                             | Description                                                                                                               |
| ------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `404`  | `No Twitter account found with the provided subject for this app` | No user in the app has a `twitter_oauth` account with the given `subject`.                                                |
| `404`  | `Twitter user no longer exists or has been suspended`             | Twitter no longer serves a profile for the account. Your app should stop retrying this `subject`.                         |
| `429`  | `Twitter account refreshes are limited to once per day`           | Privy's own limit. The linked account was refreshed or otherwise modified within the last 24 hours. Retry after 24 hours. |
| `429`  | `Twitter API rate limit exceeded, try again later`                | Twitter rate limited Privy's request. The linked account was not modified, so your app can retry shortly.                 |
| `500`  | `Unable to fetch profile from Twitter API`                        | Privy could not reach Twitter, or Twitter returned an unexpected response.                                                |
| `500`  | `Twitter API authentication failed`                               | Privy's Twitter credentials were rejected. Retrying will not help; contact Privy support.                                 |

Both `429` responses include the error code `too_many_requests`. The `404` and `500` responses do not
include an error code.