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

# Set a Twitter handle for Xquik tweet style analysis

> Store your lowercase X or Twitter handle for own-account tweet style analysis. Validate username format, replace a handle, and recover from 400, 401 or 429.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-account-x-identity-200">
      ```json theme={null}
      {
        "success": true,
        "xUsername": "elonmusk"
      }
      ```
    </Tab>

    <Tab title="400" id="response-account-x-identity-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Invalid input. Check the request body."
      }
      ```
    </Tab>

    <Tab title="401" id="response-account-x-identity-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

    <Tab title="429" id="response-account-x-identity-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

## Store your X or Twitter handle

Store one X username on your authenticated Xquik account. Send the handle
without its leading `@`. Xquik validates the syntax and stores lowercase text.

This identity helps [Analyze Style](/api-reference/styles/analyze) recognize
when the requested username matches your stored account username. That match
supports own-account tweet style analysis.

This route does not look up an X profile. It does not verify username
availability, account existence, or ownership. It also does not connect an X
account or authorize tweet, reply, like, follow, or Direct Message actions.

<Callout icon="circle-check" color="#16a34a">
  **Free.** This endpoint does not consume credits.
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  curl --fail-with-body \
    --request PUT https://xquik.com/api/v1/account/x-identity \
    --header "x-api-key: xq_YOUR_KEY_HERE" \
    --header "Content-Type: application/json" \
    --data '{"username":"elonmusk"}' | jq
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://xquik.com/api/v1/account/x-identity", {
    method: "PUT",
    headers: {
      "x-api-key": "xq_YOUR_KEY_HERE",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ username: "elonmusk" }),
  });
  const result = await response.json();
  if (!response.ok) {
    throw new Error(`${response.status} ${result.error}: ${result.message}`);
  }

  console.log(result.xUsername);
  ```

  ```python Python theme={null}
  import requests

  response = requests.put(
      "https://xquik.com/api/v1/account/x-identity",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
      json={"username": "elonmusk"},
  )
  result = response.json()
  if response.status_code != 200:
      raise RuntimeError(
          f'{response.status_code} {result["error"]}: {result["message"]}'
      )

  print(result["xUsername"])
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      body, err := json.Marshal(map[string]string{
          "username": "elonmusk",
      })
      if err != nil {
          panic(err)
      }

      req, err := http.NewRequest("PUT", "https://xquik.com/api/v1/account/x-identity", bytes.NewReader(body))
      if err != nil {
          panic(err)
      }
      req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")
      req.Header.Set("Content-Type", "application/json")

      resp, err := http.DefaultClient.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      var result map[string]interface{}
      if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
          panic(err)
      }
      if resp.StatusCode != http.StatusOK {
          panic(fmt.Sprintf("%d %v: %v", resp.StatusCode, result["error"], result["message"]))
      }

      fmt.Println(result["xUsername"])
  }
  ```
</CodeGroup>

## Format the X username

Send one `username` string. Remove the `@` prefix first.

The Xquik route accepts 1 to 15 characters. Every character must be a letter,
number, or underscore. The route rejects spaces, periods, hyphens, emoji, and `@`.

| Input | Result | Reason |
| - | - | - |
| `XDevelopers` | Stored as `xdevelopers` | Xquik lowercases uppercase letters. |
| `xquik_api` | Stored as `xquik_api` | The route accepts letters and underscores. |
| `@xquik` | `400 invalid_username` | Remove the leading `@`. |
| `xquik-api` | `400 invalid_username` | The route rejects hyphens. |
| `xquik api` | `400 invalid_username` | The route rejects spaces. |
| Empty string | `400 invalid_input` | A username is required. |

Xquik does not trim whitespace. Remove surrounding spaces before sending the
body. Store the lowercase response value as your canonical Xquik copy.

[X's username guidance](https://help.x.com/en/managing-your-account/change-x-handle)
describes a handle as the unique name shown after `@`. Native X rules and
availability checks can be stricter than this route's syntax validation.

Passing the Xquik pattern does not prove that X currently allows the handle.
It also does not prove that the handle belongs to you.

## Understand handle, display name, and user ID

An X username is also called a Twitter handle or X handle. It appears after
`@` and inside the profile URL. This endpoint stores that username only.

| Identifier | Example | Stored here? | Can it change? |
| - | - | - | - |
| X or Twitter handle | `@xquik` | Yes, without `@` | Yes, the X account can rename it. |
| Display name | `Xquik` | No | Yes |
| Numeric X user ID | `123456789` | No | No. X keeps the ID when the handle changes. |

Do not send a numeric Twitter user ID unless it is the account's
username text. This route does not convert a Twitter ID to a username.

Use [Twitter Profile Lookup](/api-reference/x/twitter-profile-lookup) when you
need profile fields from a known username or user ID. Use
[Search Users](/api-reference/x/search-users) when you need username search.

## Apply the identity to tweet style analysis

Set the handle before analyzing your own posting style. The style route
compares its requested username with this stored lowercase value.

Use this workflow:

1. Find the exact current X username.
2. Remove the leading `@` symbol.
3. Send the username through this route.
4. Save the returned lowercase `xUsername`.
5. Call Analyze Style for that same username.
6. Review the style result for the intended account.
7. Update this identity after an X username change.

Case does not affect the stored match. `XDevelopers` becomes `xdevelopers`.
Sending the same normalized username again keeps the same stored value.

Sending another valid username replaces the previous one. The response returns
the new stored value. No username history appears in this response.

This route provides no delete or clear operation. Replace the value with
another valid username when your account identity changes.

## Keep identity storage separate from X connection

This endpoint changes one Xquik account field. It does not create an
authenticated connection to X.

| Action | Performed here? | Correct workflow |
| - | - | - |
| Store a username for style matching | Yes | Call this route. |
| Verify that an X profile exists | No | Call Twitter Profile Lookup. |
| Search for a Twitter username | No | Call Search Users. |
| Connect an X account for write actions | No | Use the X account connection flow. |
| Rename the account on X | No | Change the username through X. |
| Convert a Twitter user ID to username | No | Use a profile lookup endpoint. |
| Read followers, replies, or tweets | No | Use the matching X read endpoint. |

Use [List Connected X Accounts](/api-reference/x-accounts/list) to inspect
login-backed X connections. A stored style identity and a connected X account
serve different purposes.

## Recover from X identity errors

| Status | Error | Cause | Fix |
| - | - | - | - |
| `200` | Success object | Xquik stored the lowercase username | Save `xUsername`. |
| `400` | `invalid_input` | The body is non-object or `username` is missing, empty, or non-string | Send a non-empty string. |
| `400` | `invalid_username` | The string breaks the 1-to-15-character pattern | Remove `@`, spaces, and unsupported symbols. |
| `401` | `unauthenticated` | The credential is missing or invalid | Replace the API key or bearer token. |
| `429` | `rate_limit_exceeded` | Too many requests reached the route | Wait for `Retry-After`, then retry once. |

Never retry either `400` response without changing the body. Never retry `401`
without replacing the credential.

After `429`, keep the exact intended handle. Retry after the server's delay,
then confirm the stored value through [Get Account](/api-reference/account/get).

## X username questions

### What is a Twitter handle?

A Twitter handle is the unique username displayed after `@`. X now calls it
an X username or handle. It differs from the display name.

### How can I find my Twitter username?

Open your X profile or account settings. Copy the handle shown after `@`, then
send it here without that symbol.

### Does this endpoint perform a Twitter username lookup?

No. It stores supplied text after syntax validation. It does not fetch profile
details or confirm that the username exists.

### Does it verify that I own the X account?

No. The route does not perform an ownership challenge. Use the separate X
account connection workflow for authenticated actions.

### Is a Twitter user ID the same as a username?

No. A username is the changeable handle. A user ID identifies the profile with
a separate numeric value.

### What happens if my X handle changes?

Call this route again with the new handle. The valid lowercase username
replaces the previous value.

### Does setting an X identity consume credits?

No. This authenticated account update is free.

## Headers

<ParamField header="x-api-key" type="string">
  Your Xquik API key. Generate one from the [dashboard](https://xquik.com/dashboard).
</ParamField>

<ParamField header="Authorization" type="string">
  An OAuth bearer token formatted as `Bearer YOUR_TOKEN`. Send this header or `x-api-key`, not both.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="username" type="string" required>
  X username without `@`. Send 1 to 15 letters, numbers, or underscores. The stored value becomes lowercase.
</ParamField>

## Response

### 200 OK

<ResponseField name="success" type="boolean">
  Always `true` after a successful update.
</ResponseField>

<ResponseField name="xUsername" type="string">
  Stored lowercase X username without `@`.
</ResponseField>

```json theme={null}
{
  "success": true,
  "xUsername": "elonmusk"
}
```

### 400 Invalid input

```json theme={null}
{ "error": "invalid_input", "message": "Invalid input. Check the request body." }
```

The body lacks a non-empty string `username`.

```json theme={null}
{ "error": "invalid_username", "message": "Invalid username format." }
```

The username breaks the 1-to-15-character letter, number, and underscore pattern.

### 401 Unauthenticated

```json theme={null}
{
  "error": "unauthenticated",
  "message": "Authentication required. Provide a valid API key or bearer token."
}
```

Authentication is missing or invalid. Replace the credential before retrying.

### 429 Rate limited

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}
```

Too many requests reached the route. Wait for `Retry-After` before retrying.

<Note>
  **Related.** [Get Account](/api-reference/account/get) to confirm the stored handle, [Analyze Style](/api-reference/styles/analyze) to process tweet style, or [List Connected X Accounts](/api-reference/x-accounts/list) to inspect authenticated X connections.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.