> ## 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.

# Twitter search autocomplete API for X typeahead

> Get the accounts, topics, hashtags, and cashtags X suggests for a partial search query. Build typeahead, keyword research, and ticker lookup. 1 credit each.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-search-autocomplete-200">
      ```json theme={null}
      {
        "query": "nasa",
        "users": [
          {
            "id": "11348282",
            "username": "NASA",
            "name": "NASA",
            "verified": true,
            "isBlueVerified": true
          }
        ],
        "topics": [
          {
            "topic": "nasa",
            "score": 0,
            "tokens": [],
            "inline": false
          }
        ],
        "hashtags": [],
        "cashtags": [],
        "count": 2
      }
      ```
    </Tab>

    <Tab title="400" id="response-x-search-autocomplete-400">
      ```json theme={null}
      {
        "error": "missing_query",
        "message": "Search query required. Use q."
      }
      ```
    </Tab>

    <Tab title="401" id="response-x-search-autocomplete-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required."
      }
      ```
    </Tab>

    <Tab title="402" id="response-x-search-autocomplete-402">
      ```json theme={null}
      {
        "error": "insufficient_credits",
        "message": "Insufficient credits. Top up or subscribe to continue."
      }
      ```
    </Tab>

    <Tab title="424" id="response-x-search-autocomplete-424">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

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

    <Tab title="502" id="response-x-search-autocomplete-502">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="503" id="response-x-search-autocomplete-503">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "Xquik is busy right now. Retry shortly."
      }
      ```
    </Tab>
  </Tabs>
</Panel>

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

<Note>
  `limit` is an upper bound for paid authenticated calls. When remaining credits cannot cover every suggestion, Xquik returns fewer. If zero suggestions are affordable, it returns `402 insufficient_credits`.
</Note>

<Callout icon="coins" color="#5c3327">
  **1 credit per suggestion returned** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://xquik.com/api/v1/x/search/autocomplete \
    --data-urlencode "q=nasa" \
    --data-urlencode "limit=10" \
    -H "x-api-key: xq_your_api_key_here" | jq
  ```

  ```javascript Node.js theme={null}
  const query = "nasa";
  const params = new URLSearchParams({ q: query, limit: "10" });
  const response = await fetch(`https://xquik.com/api/v1/x/search/autocomplete?${params}`, {
    headers: { "x-api-key": "xq_your_api_key_here" },
  });
  const data = await response.json();
  const suggestionRows = [
    ...data.users.map((user) => ({ type: "user", text: `@${user.username}`, label: user.name })),
    ...data.topics.map((topic) => ({ type: "topic", text: topic.topic, label: topic.topic })),
    ...data.hashtags.map((tag) => ({ type: "hashtag", text: tag.hashtag, label: tag.hashtag })),
    ...data.cashtags.map((asset) => ({
      type: "cashtag",
      text: `$${asset.ticker}`,
      label: asset.name ?? asset.ticker,
    })),
  ].map((row, index) => ({ search_query: data.query, result_rank: index + 1, ...row }));
  ```

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

  query = "nasa"
  response = requests.get(
      "https://xquik.com/api/v1/x/search/autocomplete",
      params={"q": query, "limit": 10},
      headers={"x-api-key": "xq_your_api_key_here"},
  )
  data = response.json()
  suggestions = (
      [("user", f"@{user['username']}", user["name"]) for user in data["users"]]
      + [("topic", topic["topic"], topic["topic"]) for topic in data["topics"]]
      + [("hashtag", tag["hashtag"], tag["hashtag"]) for tag in data["hashtags"]]
      + [
          ("cashtag", f"${asset['ticker']}", asset.get("name", asset["ticker"]))
          for asset in data["cashtags"]
      ]
  )
  suggestion_rows = [
      {
          "search_query": data["query"],
          "result_rank": index + 1,
          "type": kind,
          "text": text,
          "label": label,
      }
      for index, (kind, text, label) in enumerate(suggestions)
  ]
  ```
</CodeGroup>

The Node.js and Python snippets build one row per suggestion. Each row keeps
the query, the suggestion type, the text to search for, and a display label.
Store `suggestionRows` or `suggestion_rows` beside the query that produced them.

## Build a search box or keyword list

Use `GET /x/search/autocomplete` to read what X suggests while someone types.
One call returns one answer. This route has no cursor and no next page.

<CardGroup cols={2}>
  <Card title="Typeahead" icon="search">
    Send the text typed so far as `q`. Show `users`, `topics`, `hashtags`,
    and `cashtags` as separate groups.
  </Card>

  <Card title="Accounts only" icon="user-round">
    Set `types=users` to resolve a partial name or handle. Follow up with
    [Get user](/api-reference/x/twitter-profile-lookup) for the full profile.
  </Card>

  <Card title="Hashtags" icon="hash">
    Start `q` with `#`, or set `types=hashtags`. Each suggestion keeps its
    `#`.
  </Card>

  <Card title="Stocks and tokens" icon="chart-candlestick">
    Start `q` with `$`, or set `types=cashtags`. Each cashtag carries `price`,
    `marketCap`, and `dailyChangePercent`.
  </Card>

  <Card title="Keyword research" icon="list">
    Store `topics` for each seed term. Pass a topic to
    [Search tweets](/api-reference/x/search-tweets) to read matching posts.
  </Card>

  <Card title="Credit control" icon="coins">
    Set `limit` to cap the suggestions you pay for. A query with no
    suggestions costs 0 credits.
  </Card>
</CardGroup>

## Query parameters

<ParamField query="q" type="string" required>
  Text typed so far. Start it with `#` for hashtags or `$` for cashtags. A `#`
  query returns hashtags & the accounts X suggests for it. Alias: `query`.
</ParamField>

<ParamField query="types" type="string">
  Comma-separated suggestion types: `users`, `topics`, `hashtags`, or `cashtags`.
  Omit it for all 4. With only `hashtags` or only `cashtags`, Xquik adds the
  missing `#` or `$` to the query.
</ParamField>

<ParamField query="limit" type="integer">
  Most suggestions to return, from `1` to `100`. Default `20`. Accounts fill the
  limit first, then topics, hashtags, and cashtags. Aliases: `pageSize`, `count`,
  `max_results`, `maxItems`, `max_items` & `per_page`.
</ParamField>

## Headers

<ParamField header="x-api-key" type="string">
  Full account key. Sessions and OAuth also work.
</ParamField>

<ParamField header="Authorization" type="string">
  `Bearer xq_your_guest_key_here` for `paid_reads`.
</ParamField>

## Response

### 200 OK

Every list keeps the order X returns. X may rank suggestions differently per
request, so 2 calls can differ. A list is empty when X suggests nothing of its
type, or when `types` leaves it out.

<ResponseField name="query" type="string">
  The query you sent, trimmed.
</ResponseField>

<ResponseField name="users" type="object[]">
  Suggested accounts.
  **User object fields.**

  <ResponseField name="id" type="string">
    X user ID.
  </ResponseField>

  <ResponseField name="username" type="string">
    X username without the `@`.
  </ResponseField>

  <ResponseField name="name" type="string">
    Display name.
  </ResponseField>

  <ResponseField name="verified" type="boolean">
    Whether X shows any verification badge.
  </ResponseField>

  <ResponseField name="isBlueVerified" type="boolean">
    Whether X shows a blue verification badge.
  </ResponseField>

  <ResponseField name="isVerified" type="boolean">
    Whether the account holds X's legacy verification.
  </ResponseField>

  <ResponseField name="verifiedType" type="string">
    Verification category, such as `Government` or `Business`. Omitted when X names none.
  </ResponseField>

  <ResponseField name="protected" type="boolean">
    Whether the account protects its posts.
  </ResponseField>

  <ResponseField name="location" type="string">
    Public profile location. Omitted when empty.
  </ResponseField>

  <ResponseField name="profilePicture" type="string">
    Profile image URL.
  </ResponseField>

  <ResponseField name="badges" type="object[]">
    Affiliation badges X shows beside the name.

    <ResponseField name="badgeType" type="string">
      Kind of badge, such as `BusinessLabel`.
    </ResponseField>

    <ResponseField name="badgeUrl" type="string">
      Badge image URL.
    </ResponseField>

    <ResponseField name="description" type="string">
      Name of the affiliated account.
    </ResponseField>
  </ResponseField>

  <ResponseField name="isPersonaMediaGenable" type="boolean">
    X's flag for whether media can be generated from this account's persona.
  </ResponseField>

  <ResponseField name="score" type="number">
    X's rounded relevance score for the suggestion.
  </ResponseField>

  <ResponseField name="tokens" type="string[]">
    Normalized text tokens X matches the suggestion by.
  </ResponseField>

  <ResponseField name="inline" type="boolean">
    X's inline flag for the suggestion.
  </ResponseField>
</ResponseField>

<ResponseField name="topics" type="object[]">
  Suggested search phrases that are not hashtags. Each has `score`, `tokens`, and
  `inline`, as described for users.

  <ResponseField name="topic" type="string">
    Suggested search phrase.
  </ResponseField>
</ResponseField>

<ResponseField name="hashtags" type="object[]">
  Suggested hashtags. Each has `score`, `tokens`, and `inline`, as described for
  users.

  <ResponseField name="hashtag" type="string">
    Suggested hashtag, with its `#`.
  </ResponseField>
</ResponseField>

<ResponseField name="cashtags" type="object[]">
  Suggested stocks and crypto tokens.

  <ResponseField name="ticker" type="string">
    Ticker symbol without the `$`.
  </ResponseField>

  <ResponseField name="name" type="string">
    Company or token name.
  </ResponseField>

  <ResponseField name="smartTag" type="string">
    X's tag for the asset. `$TICKER` for a stock, `chain:contract` for a token.
  </ResponseField>

  <ResponseField name="currency" type="string">
    Currency of `price` and `marketCap`.
  </ResponseField>

  <ResponseField name="price" type="string">
    Latest price as decimal text, which keeps every digit.
  </ResponseField>

  <ResponseField name="marketCap" type="string">
    Market capitalization as decimal text.
  </ResponseField>

  <ResponseField name="dailyChangePercent" type="number">
    Price change over the last 24 hours, in percent.
  </ResponseField>

  <ResponseField name="logoUrl" type="string">
    Logo image URL.
  </ResponseField>

  <ResponseField name="exchangeShortName" type="string">
    Stock exchange. Stocks only.
  </ResponseField>

  <ResponseField name="contractAddress" type="string">
    Token contract address. Tokens only.
  </ResponseField>

  <ResponseField name="chainLogoUrl" type="string">
    Logo of the token's chain. Tokens only.
  </ResponseField>
</ResponseField>

<ResponseField name="count" type="number">
  Suggestions returned across all 4 lists. Each costs 1 credit.
</ResponseField>

```json theme={null}
{
  "query": "$tsla",
  "users": [],
  "topics": [{ "topic": "$tsla", "score": 0, "tokens": [], "inline": false }],
  "hashtags": [],
  "cashtags": [
    {
      "ticker": "TSLA",
      "name": "Tesla Inc",
      "smartTag": "$TSLA",
      "currency": "USD",
      "price": "370.589999999",
      "marketCap": "1463662787286.778808593",
      "dailyChangePercent": 4.6539,
      "logoUrl": "https://abs.twimg.com/finance/v1/stock/TSLA.png",
      "exchangeShortName": "NASDAQ"
    }
  ],
  "count": 2
}
```

Example values are illustrative. Live responses reflect current X data.

### 400 Invalid request

```json theme={null}
{ "error": "missing_query", "message": "Search query required. Use q." }
```

`q` is missing or blank. Send the text typed so far.

```json theme={null}
{
  "error": "invalid_params",
  "message": "Send types as users, topics, hashtags or cashtags, separated by commas.",
  "parameter": "types"
}
```

`types` names an unknown suggestion type. Use `users`, `topics`, `hashtags`, or `cashtags`.

### 401 Unauthenticated

Anonymous requests get `WWW-Authenticate: Bearer` and a guest wallet checkout action. This is not a Payment challenge.

```json theme={null}
{ "error": "unauthenticated" }
```

### 402 Payment required

Account keys get account options. Guest keys get guest top-up only.
No checkout starts automatically. Confirm any payment action.

### 502 X API unavailable

```json theme={null}
{ "error": "x_api_unavailable" }
```

The read service returned an error. Retry after a short delay.

### 429 Rate limit exceeded

```json theme={null}
{ "error": "rate_limit_exceeded", "retryAfter": 60 }
```

You exceeded your tier rate limit. Wait for the `Retry-After` header before retrying.

### 424 Dependency failed

```json theme={null}
{ "error": "x_api_unavailable" }
```

The normalized v1 response contract can return 424 when the read service is unavailable.

## Search autocomplete API questions

### How do I get Twitter search suggestions programmatically?

Call `GET /x/search/autocomplete` with the text typed so far in `q`.
Read `users`, `topics`, `hashtags`, and `cashtags` from the response.

### How do I get hashtag suggestions?

Start `q` with `#`, such as `#nas`. You can also send `types=hashtags` with a
plain word. Each suggestion in `hashtags` keeps its `#`.

### How do I look up a stock or crypto ticker?

Start `q` with `$`, such as `$tsla`, and read `cashtags`.
Use `smartTag` to tell a stock from tokens that share its ticker.

### How much does a search autocomplete request cost?

Each returned suggestion costs 1 credit. `count` states the total.
A query with no suggestions costs 0 credits. Errors cost 0 credits.

### Does the response depend on my X account?

No. The response holds public suggestion data only. It needs no connected X
account.

### Does this replace X's official API?

No. This page documents Xquik, an independent third-party service.
It does not document X's official API.

<Note>
  **Next steps.** [Search users](/api-reference/x/search-users) for full profiles with filters, [Search tweets](/api-reference/x/search-tweets) to read posts for a suggestion, or [Get trends](/api-reference/x/trends) for trending topics by region.
</Note>

<div className="related-api-links">
  <Accordion title="Related follower, list & community APIs" icon="link">
    * Profiles: [Search users](/api-reference/x/search-users) · [Search autocomplete](/api-reference/x/search-autocomplete) · [Get user](/api-reference/x/twitter-profile-lookup) · [Batch users](/api-reference/x/batch-users)
    * Followers: [Followers](/api-reference/x/followers) · [Following](/api-reference/x/following) · [Follower IDs](/api-reference/x/follower-ids) · [Following IDs](/api-reference/x/following-ids) · [Creator subscriptions](/api-reference/x/user-subscriptions) · [Affiliates](/api-reference/x/user-affiliates) · [Similar accounts](/api-reference/x/user-similar) · [Verified followers](/api-reference/x/verified-followers) · [Followers you know](/api-reference/x/followers-you-know) · [Check follower](/api-reference/x/check-follower)
    * Lists: [Search lists](/api-reference/x/search-lists) · [User lists](/api-reference/x/user-lists) · [List memberships](/api-reference/x/user-list-memberships) · [List members](/api-reference/x/list-members) · [List followers](/api-reference/x/list-followers)
    * Communities: [Find](/api-reference/x/community-find) · [Popular](/api-reference/x/community-popular) · [Topics](/api-reference/x/community-topics) · [Suggested](/api-reference/x/community-suggested) · [Details](/api-reference/x/community-info) · [Members](/api-reference/x/community-members) · [Moderators](/api-reference/x/community-moderators) · [Timeline](/api-reference/x/community-tweets) · [Media](/api-reference/x/community-media) · [Keyword search](/api-reference/x/community-search)
  </Accordion>
</div>


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