Twitter search autocomplete API for X typeahead

{
  "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
}

{
  "error": "missing_query",
  "message": "Search query required. Use q."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

GET

autocomplete

Twitter search autocomplete API for X typeahead

curl --request GET \
  --url https://xquik.com/api/v1/x/search/autocomplete

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/search/autocomplete"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "query": "<string>",
  "users": [
    {
      "id": "<string>",
      "username": "<string>",
      "name": "<string>",
      "verified": true,
      "isBlueVerified": true,
      "isVerified": true,
      "verifiedType": "<string>",
      "protected": true,
      "location": "<string>",
      "profilePicture": "<string>",
      "badges": [
        {
          "badgeType": "<string>",
          "badgeUrl": "<string>",
          "description": "<string>"
        }
      ],
      "isPersonaMediaGenable": true,
      "score": 123,
      "tokens": [
        "<string>"
      ],
      "inline": true
    }
  ],
  "topics": [
    {
      "topic": "<string>"
    }
  ],
  "hashtags": [
    {
      "hashtag": "<string>"
    }
  ],
  "cashtags": [
    {
      "ticker": "<string>",
      "name": "<string>",
      "smartTag": "<string>",
      "currency": "<string>",
      "price": "<string>",
      "marketCap": "<string>",
      "dailyChangePercent": 123,
      "logoUrl": "<string>",
      "exchangeShortName": "<string>",
      "contractAddress": "<string>",
      "chainLogoUrl": "<string>"
    }
  ],
  "count": 123
}

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.

1 credit per suggestion returned · All plans from $0.00012/credit

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

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 }));

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)
]

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

Typeahead

Send the text typed so far as q. Show users, topics, hashtags, and cashtags as separate groups.

Accounts only

Set types=users to resolve a partial name or handle. Follow up with Get user for the full profile.

Hashtags

Start q with #, or set types=hashtags. Each suggestion keeps its #.

Stocks and tokens

Start q with $, or set types=cashtags. Each cashtag carries price, marketCap, and dailyChangePercent.

Keyword research

Store topics for each seed term. Pass a topic to Search tweets to read matching posts.

Credit control

Set limit to cap the suggestions you pay for. A query with no suggestions costs 0 credits.

Query parameters

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.

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.

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.

Headers

string

Full account key. Sessions and OAuth also work.

string

Bearer xq_your_guest_key_here for paid_reads.

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.

string

The query you sent, trimmed.

object[]

Suggested accounts. User object fields.

string

X user ID.

string

X username without the @.

string

Display name.

boolean

Whether X shows any verification badge.

boolean

Whether X shows a blue verification badge.

boolean

Whether the account holds X’s legacy verification.

string

Verification category, such as Government or Business. Omitted when X names none.

boolean

Whether the account protects its posts.

string

Public profile location. Omitted when empty.

string

Profile image URL.

object[]

Affiliation badges X shows beside the name.

string

Kind of badge, such as BusinessLabel.

string

Badge image URL.

string

Name of the affiliated account.

boolean

X’s flag for whether media can be generated from this account’s persona.

number

X’s rounded relevance score for the suggestion.

string[]

Normalized text tokens X matches the suggestion by.

boolean

X’s inline flag for the suggestion.

object[]

Suggested search phrases that are not hashtags. Each has score, tokens, and inline, as described for users.

string

Suggested search phrase.

object[]

Suggested hashtags. Each has score, tokens, and inline, as described for users.

string

Suggested hashtag, with its #.

object[]

Suggested stocks and crypto tokens.

string

Ticker symbol without the $.

string

Company or token name.

string

X’s tag for the asset. $TICKER for a stock, chain:contract for a token.

string

Currency of price and marketCap.

string

Latest price as decimal text, which keeps every digit.

string

Market capitalization as decimal text.

number

Price change over the last 24 hours, in percent.

string

Logo image URL.

string

Stock exchange. Stocks only.

string

Token contract address. Tokens only.

string

Logo of the token’s chain. Tokens only.

number

Suggestions returned across all 4 lists. Each costs 1 credit.

{
  "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

{ "error": "missing_query", "message": "Search query required. Use q." }

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

{
  "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.

{ "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

{ "error": "x_api_unavailable" }

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

429 Rate limit exceeded

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

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

424 Dependency failed

{ "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.

Next steps. Search users for full profiles with filters, Search tweets to read posts for a suggestion, or Get trends for trending topics by region.

{
  "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
}

{
  "error": "missing_query",
  "message": "Search query required. Use q."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

Twitter search autocomplete API for X typeahead

curl --request GET \
  --url https://xquik.com/api/v1/x/search/autocomplete

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/search/autocomplete"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "query": "<string>",
  "users": [
    {
      "id": "<string>",
      "username": "<string>",
      "name": "<string>",
      "verified": true,
      "isBlueVerified": true,
      "isVerified": true,
      "verifiedType": "<string>",
      "protected": true,
      "location": "<string>",
      "profilePicture": "<string>",
      "badges": [
        {
          "badgeType": "<string>",
          "badgeUrl": "<string>",
          "description": "<string>"
        }
      ],
      "isPersonaMediaGenable": true,
      "score": 123,
      "tokens": [
        "<string>"
      ],
      "inline": true
    }
  ],
  "topics": [
    {
      "topic": "<string>"
    }
  ],
  "hashtags": [
    {
      "hashtag": "<string>"
    }
  ],
  "cashtags": [
    {
      "ticker": "<string>",
      "name": "<string>",
      "smartTag": "<string>",
      "currency": "<string>",
      "price": "<string>",
      "marketCap": "<string>",
      "dailyChangePercent": 123,
      "logoUrl": "<string>",
      "exchangeShortName": "<string>",
      "contractAddress": "<string>",
      "chainLogoUrl": "<string>"
    }
  ],
  "count": 123
}

​Build a search box or keyword list

Typeahead

Accounts only

Hashtags

Stocks and tokens

Keyword research

Credit control

​Query parameters

​Headers

​Response

​200 OK

​400 Invalid request

​401 Unauthenticated

​402 Payment required

​502 X API unavailable

​429 Rate limit exceeded

​424 Dependency failed

​Search autocomplete API questions

​How do I get Twitter search suggestions programmatically?

​How do I get hashtag suggestions?

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

​How much does a search autocomplete request cost?

​Does the response depend on my X account?

​Does this replace X’s official API?

Build a search box or keyword list

Query parameters

Headers

Response

200 OK

400 Invalid request

401 Unauthenticated

402 Payment required

502 X API unavailable

429 Rate limit exceeded

424 Dependency failed

Search autocomplete API questions

How do I get Twitter search suggestions programmatically?

How do I get hashtag suggestions?

How do I look up a stock or crypto ticker?

How much does a search autocomplete request cost?

Does the response depend on my X account?

Does this replace X’s official API?