Twitter hashflags API: list X hashtag emoji

{
  "hashflags": [
    {
      "hashtag": "AION2",
      "assetUrl": "https://abs.twimg.com/hashflags/BF-16692_AIon2_jp_Hashmoji_v3/BF-16692_AIon2_jp_Hashmoji_v3.png",
      "startsAt": "2026-10-02T10:00:00.000Z",
      "endsAt": "2027-01-03T14:59:00.000Z",
      "isHashfettiEnabled": false
    }
  ],
  "count": 1,
  "total": 1
}

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

hashflags

Twitter hashflags API: list X hashtag emoji

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

package main

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

func main() {

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

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

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

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

	fmt.Println(string(body))

}

{
  "hashflags": [
    {
      "hashtag": "<string>",
      "assetUrl": "<string>",
      "startsAt": "<string>",
      "endsAt": "<string>",
      "isHashfettiEnabled": true,
      "animations": [
        {}
      ]
    }
  ],
  "count": 123,
  "total": 123,
  "message": "<string>"
}

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

curl -G https://xquik.com/api/v1/x/hashflags \
  --data-urlencode "q=football" \
  --data-urlencode "limit=20" \
  -H "x-api-key: xq_your_api_key_here" | jq

const params = new URLSearchParams({ q: "football", limit: "20" });
const response = await fetch(`https://xquik.com/api/v1/x/hashflags?${params}`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const data = await response.json();
const hashflagRows = data.hashflags.map((hashflag) => ({
  hashtag: hashflag.hashtag,
  image_url: hashflag.assetUrl,
  starts_at: hashflag.startsAt,
  ends_at: hashflag.endsAt,
  animation_count: hashflag.animations.length,
}));

for (const row of hashflagRows) {
  process.stdout.write(`${JSON.stringify(row)}\n`);
}

import json
import requests

response = requests.get(
    "https://xquik.com/api/v1/x/hashflags",
    params={"q": "football", "limit": 20},
    headers={"x-api-key": "xq_your_api_key_here"},
)
data = response.json()
hashflag_rows = [
    {
        "hashtag": hashflag["hashtag"],
        "image_url": hashflag["assetUrl"],
        "starts_at": hashflag["startsAt"],
        "ends_at": hashflag["endsAt"],
        "animation_count": len(hashflag["animations"]),
    }
    for hashflag in data["hashflags"]
]
for row in hashflag_rows:
    print(json.dumps(row))

Use GET /x/hashflags to list X’s hashflags. A hashflag is the custom emoji X shows after a hashtag for a set time. Each returned hashflag costs 1 credit. Filters and limit lower the cost. An empty result costs nothing.

Track branded hashtags

The endpoint lists the hashflags that run now. Send activeOnly=false to add ended and upcoming ones. Use q to keep hashtags that contain your text. startsAt and endsAt give the time X shows each emoji. assetUrl is the emoji image. animations lists the animations X plays, such as on a like. X lists a few hundred hashflags. Send limit when you need only some.

Query parameters

string

Text the hashtag contains, such as football. Case insensitive. A leading # is ignored. Alias: query.

boolean

default:"true"

Keeps hashflags that run now. Send false to add ended and upcoming ones.

integer

Maximum hashflags to return, starting at 1. Omit it for every match. Your credit balance can return fewer. Aliases: pageSize, count, max_results, maxItems, max_items & per_page.

Headers

string

Send a full Xquik account API key.

string

Bearer xq_your_guest_key_here for paid_reads.

Response

200 OK

object[]

Hashflags that match your filters, in X’s order. Hashflag object fields.

string

Hashtag text without #. X also lists some plain phrases.

string

Image of the emoji.

string

When X starts showing the emoji, in UTC.

string

When X stops showing the emoji, in UTC.

boolean

Whether X marks the hashflag for its hashfetti effect.

object[]

Animations X plays for the hashtag. Often empty. Each has context, such as Like, assetUrl, and priority.

number

Hashflags returned and charged.

number

Hashflags that match the filters, before limit.

string

What to send instead. Present only when no hashflag matches.

{
  "hashflags": [
    {
      "hashtag": "College Football",
      "assetUrl": "https://abs.twimg.com/hashflags/2026FootballCustomLikeEvergreenv3/2026FootballCustomLikeEvergreenv3.png",
      "startsAt": "2026-10-02T00:00:00.000Z",
      "endsAt": "2027-01-10T00:00:00.000Z",
      "isHashfettiEnabled": false,
      "animations": [
        {
          "context": "Like",
          "assetUrl": "https://abs.twimg.com/hashflags/2026FootballCustomLikeEvergreenv3/2026FootballCustomLikeEvergreenv3_sakura_0.json",
          "priority": 1
        }
      ]
    }
  ],
  "count": 1,
  "total": 1
}

A filter that matches no hashflag returns an empty list and a message:

{
  "hashflags": [],
  "count": 0,
  "total": 0,
  "message": "No hashflag runs now. Send activeOnly=false to list the rest."
}

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.

503 Service busy

{ "error": "x_api_unavailable" }

Xquik is busy. Wait for Retry-After, then retry.

429 Rate limit exceeded

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

The Xquik tier limit blocked the request. Use Retry-After when present. Otherwise, use the JSON retryAfter field.

424 Dependency failed

{ "error": "x_api_unavailable" }

The opt-in normalized contract returns 424 when the read service fails. Send xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.

Twitter hashflags API questions

What is a Twitter hashflag?

A hashflag is a custom emoji X shows after a hashtag for a set time. Brands and events use them. Some people call them hashmoji.

How do I list the hashflags that run now?

Call GET /x/hashflags without parameters. The response lists every hashflag X shows at that moment.

How do I find the emoji of 1 hashtag?

Send q with the hashtag text, with or without #. Read assetUrl from the matching hashflag.

How much does a hashflags request cost?

Each returned hashflag costs 1 credit. An empty result costs nothing. Add q or limit to return fewer hashflags.

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 tweets finds the posts that use a hashtag.

{
  "hashflags": [
    {
      "hashtag": "AION2",
      "assetUrl": "https://abs.twimg.com/hashflags/BF-16692_AIon2_jp_Hashmoji_v3/BF-16692_AIon2_jp_Hashmoji_v3.png",
      "startsAt": "2026-10-02T10:00:00.000Z",
      "endsAt": "2027-01-03T14:59:00.000Z",
      "isHashfettiEnabled": false
    }
  ],
  "count": 1,
  "total": 1
}

{
  "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 hashflags API: list X hashtag emoji

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

package main

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

func main() {

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

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

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

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

	fmt.Println(string(body))

}

{
  "hashflags": [
    {
      "hashtag": "<string>",
      "assetUrl": "<string>",
      "startsAt": "<string>",
      "endsAt": "<string>",
      "isHashfettiEnabled": true,
      "animations": [
        {}
      ]
    }
  ],
  "count": 123,
  "total": 123,
  "message": "<string>"
}

Overview

X API

X write

Trends

Radar

Account

API keys

Guest wallets

Credits

X accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Twitter hashflags API: list X hashtag emoji

Track branded hashtags

Query parameters

Headers

Response

200 OK

401 Unauthenticated

402 Payment required

502 X API unavailable

503 Service busy

429 Rate limit exceeded

424 Dependency failed

Twitter hashflags API questions

What is a Twitter hashflag?

How do I list the hashflags that run now?

How do I find the emoji of 1 hashtag?

How much does a hashflags request cost?

Does this replace X’s official API?

​Track branded hashtags

​Query parameters

​Headers

​Response

​200 OK

​401 Unauthenticated

​402 Payment required

​502 X API unavailable

​503 Service busy

​429 Rate limit exceeded

​424 Dependency failed

​Twitter hashflags API questions

​What is a Twitter hashflag?

​How do I list the hashflags that run now?

​How do I find the emoji of 1 hashtag?

​How much does a hashflags request cost?

​Does this replace X’s official API?

Track branded hashtags

Query parameters

Headers

Response

200 OK

401 Unauthenticated

402 Payment required

502 X API unavailable

503 Service busy

429 Rate limit exceeded

424 Dependency failed

Twitter hashflags API questions

What is a Twitter hashflag?

How do I list the hashflags that run now?

How do I find the emoji of 1 hashtag?

How much does a hashflags request cost?

Does this replace X’s official API?