API Documentation

Twitter / X Trending API

Read the public trending tweet timeline by language, region and optional topic.

Test API

Read the public trending tweet timeline by language, region and optional topic.

Open product page and API Tester

Endpoint and authentication

POST https://api.goanyapi.com/api/v1/twitter/trending

Results return synchronously, without tasks or polling. Authenticate using Authorization: Bearer YOUR_API_KEY and send a JSON request body. There are no Path or Query parameters.

Input parameters

Returns up to 20 records per request; actual results may be fewer. Pagination is not supported. Do not send count, page_size or cursor.

ParameterLocationTypeRequiredDefaultConstraints and meaning
AuthorizationHeaderstringYes—Bearer YOUR_API_KEY
Content-TypeHeaderstringYesapplication/jsonapplication/json
languageJSON bodystringNo"en"See complete enum below
placeIdJSON bodystringNo""See complete enum below
topicIdJSON bodystringNo—Optional topic ID or full https://x.com/i/topics/<topicId> URL. Not a region ID; not an enum. maxLength=2048

topicId accepts a numeric topic ID or https://x.com/i/topics/123 URL; it is not an enum. placeId identifies a region and cannot replace topicId or woeid.

language

ValueName
"en"English (en)
"ja"日本語 (ja)
"zh"中文 (zh)
"ko"한국어 (ko)
"es"Español (es)
"fr"Français (fr)
"de"Deutsch (de)
"pt"Português (pt)
"ru"Русский (ru)
"ar"العربية (ar)
"hi"हिन्दी (hi)
"id"Bahasa Indonesia (id)
"th"ไทย (th)
"tr"Türkçe (tr)
"vi"Tiếng Việt (vi)

placeId

ValueName
""全球
"-7608764736147602991"🇺🇸 United States
"-2938771511404889033"🇩🇿 Algeria
"5565096121164180265"🇦🇷 Argentina
"4545484598816818534"🇦🇺 Australia
"3477066258611901349"🇦🇹 Austria
"-6967522436594057822"🇧🇩 Bangladesh
"8700865690535483778"🇧🇪 Belgium
"1950197124717128353"🇧🇷 Brazil
"3708319748991051719"🇨🇦 Canada
"5162197366559151326"🇨🇱 Chile
"448449062339483107"🇨🇴 Colombia
"7736400604048538601"🇨🇿 Czech Republic
"-4424729568631920893"🇩🇰 Denmark
"5639574119361710880"🇪🇨 Ecuador
"-4154065666575264154"🇪🇬 Egypt
"-4343619646806415630"🇪🇹 Ethiopia
"-1744726079396219878"🇫🇮 Finland
"-882767250859714689"🇫🇷 France
"-158432913530051802"🇩🇪 Germany
"-4571337146556827642"🇬🇭 Ghana
"3379932461505701466"🇬🇷 Greece
"-9099280338087611406"🇭🇺 Hungary
"-5165415742961667872"🇮🇳 India
"-3568670787064367969"🇮🇩 Indonesia
"2820826012199272570"🇮🇷 Iran
"-5319640165985647807"🇮🇶 Iraq
"-1556106695608941113"🇮🇪 Ireland
"3376413446669583689"🇮🇱 Israel
"-4063967790046936818"🇮🇹 Italy
"-2995833801110313328"🇯🇲 Jamaica
"499763682993518708"🇯🇵 Japan
"-260501929978120120"🇯🇴 Jordan
"1706136829559624331"🇰🇪 Kenya
"-3241657007340602969"🇰🇼 Kuwait
"6357909739404339665"🇱🇧 Lebanon
"-8776409192903084900"🇲🇾 Malaysia
"2689506185291075782"🇲🇽 Mexico
"-5333313881682429798"🇲🇦 Morocco
"-8674639883747605872"🇳🇱 Netherlands
"793650451909123257"🇳🇿 New Zealand
"6463355099376608651"🇳🇬 Nigeria
"930197452956643198"🇳🇴 Norway
"-1432840641003940880"🇴🇲 Oman
"7250935481943878042"🇵🇰 Pakistan
"3313135070624720100"🇵🇪 Peru
"-354342964243026931"🇵🇭 Philippines
"-2808195226817565729"🇵🇱 Poland
"-9108274811673285316"🇵🇹 Portugal
"-6535811615842162329"🇶🇦 Qatar
"-625131485298729454"🇷🇴 Romania
"6274701892295617822"🇷🇺 Russia
"626799985901619848"🇸🇦 Saudi Arabia
"2668868410128916434"🇸🇬 Singapore
"-2478090862324094135"🇿🇦 South Africa
"-4607653479203584261"🇰🇷 South Korea
"-1378972998044664988"🇪🇸 Spain
"1674261238603557541"🇱🇰 Sri Lanka
"-9029363556881223240"🇸🇪 Sweden
"5655432603301324742"🇨🇭 Switzerland
"4193143159185317023"🇹🇿 Tanzania
"-7544610135368989548"🇹🇭 Thailand
"6763434224275225245"🇹🇳 Tunisia
"7506474075071901506"🇹🇷 Turkey
"598148624890232477"🇺🇦 Ukraine
"4567653256866191997"🇦🇪 United Arab Emirates
"7212154512116281289"🇬🇧 United Kingdom
"2553902795103616732"🇻🇳 Vietnam
"302730704137459992"🇻🇪 Venezuela

Request example

POST /api/v1/twitter/trending
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "language": "en"
}

Output fields

Success returns HTTP 200. Business results are in data.result. Null, empty strings, empty arrays and missing business fields are preserved; zero is a valid statistic. Empty display fields do not invalidate an otherwise successful request.

FieldTypeMeaning
codestringok on success; error code otherwise
messagestringStatus message
data.resultobject / nullBusiness data; null is preserved
data.creditsUsedintegerCredits charged using current configuration
data.remainingCreditsnumberBalance after settlement
data.result.woeidstringPublic business field; may be null, empty or absent
data.result.trendsarrayRecords in this response
data.result.trends[].namestringPublic business field; may be null, empty or absent
data.result.trends[].querystringPublic business field; may be null, empty or absent
data.result.trends[].urlstringPublic business field; may be null, empty or absent
data.result.trends[].tweetVolumenull (observed)Public business field; may be null, empty or absent
data.result.createdAtstringPublic business field; may be null, empty or absent
data.result.locationstringPublic business field; may be null, empty or absent
data.result.asOfstringPublic business field; may be null, empty or absent
data.result.tweetsarrayRecords in this response
data.result.tweets[].authorobjectPublic business field; may be null, empty or absent
data.result.tweets[].author.namestringPublic business field; may be null, empty or absent
data.result.tweets[].author.screen_namestringPublic business field; may be null, empty or absent
data.result.tweets[].author.idstringPublic business field; may be null, empty or absent
data.result.tweets[].urlstringPublic business field; may be null, empty or absent
data.result.tweets[].created_atstringPublic business field; may be null, empty or absent
data.result.tweets[].viewsstringPublic business field; may be null, empty or absent
data.result.tweets[].textstringPublic business field; may be null, empty or absent
data.result.tweets[].countsobjectPublic business field; may be null, empty or absent
data.result.tweets[].counts.bookmark_countintegerPublic business field; may be null, empty or absent
data.result.tweets[].counts.favorite_countintegerPublic business field; may be null, empty or absent
data.result.tweets[].counts.quote_countintegerPublic business field; may be null, empty or absent
data.result.tweets[].counts.retweet_countintegerPublic business field; may be null, empty or absent
data.result.tweets[].counts.reply_countintegerPublic business field; may be null, empty or absent
data.result.tweets[].cardobjectPublic business field; may be null, empty or absent
data.result.tweets[].card.namestringPublic business field; may be null, empty or absent
data.result.tweets[].card.titlestringPublic business field; may be null, empty or absent
data.result.tweets[].card.imageobjectPublic business field; may be null, empty or absent
data.result.tweets[].card.image.altstringPublic business field; may be null, empty or absent
data.result.tweets[].card.image.urlstringPublic business field; may be null, empty or absent
data.result.tweets[].card.image.widthintegerPublic business field; may be null, empty or absent
data.result.tweets[].card.image.heightintegerPublic business field; may be null, empty or absent
data.result.tweets[].card.urlstringPublic business field; may be null, empty or absent
data.result.tweets[].card.domainstringPublic business field; may be null, empty or absent
data.result.tweets[].card.descriptionstringPublic business field; may be null, empty or absent
data.result.tweets[].quotednull (observed)Public business field; may be null, empty or absent
data.result.tweets[].mediaarrayPublic business field; may be null, empty or absent
data.result.tweets[].media[].typestringPublic business field; may be null, empty or absent
data.result.tweets[].media[].urlstringPublic business field; may be null, empty or absent
data.result.tweets[].media[].expanded_urlstringPublic business field; may be null, empty or absent
data.result.tweets[].media[].altstringPublic business field; may be null, empty or absent
data.result.tweets[].media[].video_infostringPublic business field; may be null, empty or absent
data.result.tweets[].langstringPublic business field; may be null, empty or absent
data.result.tweets[].linksarrayPublic business field; may be null, empty or absent
data.result.tweets[].links[].displaynull (observed)Public business field; may be null, empty or absent
data.result.tweets[].links[].tconull (observed)Public business field; may be null, empty or absent
data.result.tweets[].links[].expandedstringPublic business field; may be null, empty or absent
data.result.tweets[].idstringPublic business field; may be null, empty or absent

This endpoint has no pagination parameters.

Real response example

Saved from a real successful response with public business fields. The example omits live data.creditsUsed and data.remainingCredits, which use current configuration and account balance. No list records are omitted. Media URLs may expire. Displaying the example sends no request or charge.

{
  "code": "ok",
  "message": "ok",
  "data": {
    "result": {
      "woeid": "1",
      "location": "Worldwide",
      "asOf": "2026-11-16T02:48:20Z",
      "createdAt": "2026-11-15T06:55:37Z",
      "trends": [
        {
          "name": "Steelers",
          "query": "Steelers",
          "url": "http://twitter.com/search?q=Steelers",
          "tweetVolume": null
        },
        {
          "name": "Cowboys",
          "query": "Cowboys",
          "url": "http://twitter.com/search?q=Cowboys",
          "tweetVolume": null
        },
        {
          "name": "Bengals",
          "query": "Bengals",
          "url": "http://twitter.com/search?q=Bengals",
          "tweetVolume": null
        },
        {
          "name": "#ブラックサンダーとミルクマニア",
          "query": "%23%E3%83%96%E3%83%A9%E3%83%83%E3%82%AF%E3%82%B5%E3%83%B3%E3%83%80%E3%83%BC%E3%81%A8%E3%83%9F%E3%83%AB%E3%82%AF%E3%83%9E%E3%83%8B%E3%82%A2",
          "url": "http://twitter.com/search?q=%23%E3%83%96%E3%83%A9%E3%83%83%E3%82%AF%E3%82%B5%E3%83%B3%E3%83%80%E3%83%BC%E3%81%A8%E3%83%9F%E3%83%AB%E3%82%AF%E3%83%9E%E3%83%8B%E3%82%A2",
          "tweetVolume": null
        },
        {
          "name": "#はま寿司の旨ねた冬祭り",
          "query": "%23%E3%81%AF%E3%81%BE%E5%AF%BF%E5%8F%B8%E3%81%AE%E6%97%A8%E3%81%AD%E3%81%9F%E5%86%AC%E7%A5%AD%E3%82%8A",
          "url": "http://twitter.com/search?q=%23%E3%81%AF%E3%81%BE%E5%AF%BF%E5%8F%B8%E3%81%AE%E6%97%A8%E3%81%AD%E3%81%9F%E5%86%AC%E7%A5%AD%E3%82%8A",
          "tweetVolume": null
        },
        {
          "name": "49ers",
          "query": "49ers",
          "url": "http://twitter.com/search?q=49ers",
          "tweetVolume": null
        },
        {
          "name": "#クーリッシュカラースプレーでた",
          "query": "%23%E3%82%AF%E3%83%BC%E3%83%AA%E3%83%83%E3%82%B7%E3%83%A5%E3%82%AB%E3%83%A9%E3%83%BC%E3%82%B9%E3%83%97%E3%83%AC%E3%83%BC%E3%81%A7%E3%81%9F",
          "url": "http://twitter.com/search?q=%23%E3%82%AF%E3%83%BC%E3%83%AA%E3%83%83%E3%82%B7%E3%83%A5%E3%82%AB%E3%83%A9%E3%83%BC%E3%82%B9%E3%83%97%E3%83%AC%E3%83%BC%E3%81%A7%E3%81%9F",
          "tweetVolume": null
        },
        {
          "name": "通信障害",
          "query": "%E9%80%9A%E4%BF%A1%E9%9A%9C%E5%AE%B3",
          "url": "http://twitter.com/search?q=%E9%80%9A%E4%BF%A1%E9%9A%9C%E5%AE%B3",
          "tweetVolume": null
        },
        {
          "name": "Ferro",
          "query": "Ferro",
          "url": "http://twitter.com/search?q=Ferro",
          "tweetVolume": null
        },
        {
          "name": "Aaron Rodgers",
          "query": "%22Aaron+Rodgers%22",
          "url": "http://twitter.com/search?q=%22Aaron+Rodgers%22",
          "tweetVolume": null
        },
        {
          "name": "#UKKJKemenag2026",
          "query": "%23UKKJKemenag2026",
          "url": "http://twitter.com/search?q=%23UKKJKemenag2026",
          "tweetVolume": null
        },
        {
          "name": "NTTドコモ",
          "query": "NTT%E3%83%89%E3%82%B3%E3%83%A2",
          "url": "http://twitter.com/search?q=NTT%E3%83%89%E3%82%B3%E3%83%A2",
          "tweetVolume": null
        },
        {
          "name": "DK Metcalf",
          "query": "%22DK+Metcalf%22",
          "url": "http://twitter.com/search?q=%22DK+Metcalf%22",
          "tweetVolume": null
        },
        {
          "name": "Niners",
          "query": "Niners",
          "url": "http://twitter.com/search?q=Niners",
          "tweetVolume": null
        },
        {
          "name": "#ProvaDeFogo",
          "query": "%23ProvaDeFogo",
          "url": "http://twitter.com/search?q=%23ProvaDeFogo",
          "tweetVolume": null
        },
        {
          "name": "Jordan Battle",
          "query": "%22Jordan+Battle%22",
          "url": "http://twitter.com/search?q=%22Jordan+Battle%22",
          "tweetVolume": null
        },
        {
          "name": "Joe Burrow",
          "query": "%22Joe+Burrow%22",
          "url": "http://twitter.com/search?q=%22Joe+Burrow%22",
          "tweetVolume": null
        },
        {
          "name": "Jerry",
          "query": "Jerry",
          "url": "http://twitter.com/search?q=Jerry",
          "tweetVolume": null
        },
        {
          "name": "実刑判決",
          "query": "%E5%AE%9F%E5%88%91%E5%88%A4%E6%B1%BA",
          "url": "http://twitter.com/search?q=%E5%AE%9F%E5%88%91%E5%88%A4%E6%B1%BA",
          "tweetVolume": null
        },
        {
          "name": "Scottie Barnes",
          "query": "%22Scottie+Barnes%22",
          "url": "http://twitter.com/search?q=%22Scottie+Barnes%22",
          "tweetVolume": null
        },
        {
          "name": "ジャンポケ斉藤慎二",
          "query": "%E3%82%B8%E3%83%A3%E3%83%B3%E3%83%9D%E3%82%B1%E6%96%89%E8%97%A4%E6%85%8E%E4%BA%8C",
          "url": "http://twitter.com/search?q=%E3%82%B8%E3%83%A3%E3%83%B3%E3%83%9D%E3%82%B1%E6%96%89%E8%97%A4%E6%85%8E%E4%BA%8C",
          "tweetVolume": null
        },
        {
          "name": "Von Miller",
          "query": "%22Von+Miller%22",
          "url": "http://twitter.com/search?q=%22Von+Miller%22",
          "tweetVolume": null
        },
        {
          "name": "UKKJ 2026",
          "query": "%22UKKJ+2026%22",
          "url": "http://twitter.com/search?q=%22UKKJ+2026%22",
          "tweetVolume": null
        },
        {
          "name": "ロケバス内",
          "query": "%E3%83%AD%E3%82%B1%E3%83%90%E3%82%B9%E5%86%85",
          "url": "http://twitter.com/search?q=%E3%83%AD%E3%82%B1%E3%83%90%E3%82%B9%E5%86%85",
          "tweetVolume": null
        },
        {
          "name": "Purdy",
          "query": "Purdy",
          "url": "http://twitter.com/search?q=Purdy",
          "tweetVolume": null
        },
        {
          "name": "Christian Parker",
          "query": "%22Christian+Parker%22",
          "url": "http://twitter.com/search?q=%22Christian+Parker%22",
          "tweetVolume": null
        },
        {
          "name": "性的暴行の罪",
          "query": "%E6%80%A7%E7%9A%84%E6%9A%B4%E8%A1%8C%E3%81%AE%E7%BD%AA",
          "url": "http://twitter.com/search?q=%E6%80%A7%E7%9A%84%E6%9A%B4%E8%A1%8C%E3%81%AE%E7%BD%AA",
          "tweetVolume": null
        },
        {
          "name": "Chase Brown",
          "query": "%22Chase+Brown%22",
          "url": "http://twitter.com/search?q=%22Chase+Brown%22",
          "tweetVolume": null
        },
        {
          "name": "Pickens",
          "query": "Pickens",
          "url": "http://twitter.com/search?q=Pickens",
          "tweetVolume": null
        },
        {
          "name": "ANV 2YEARS SECRET LOVE",
          "query": "%22ANV+2YEARS+SECRET+LOVE%22",
          "url": "http://twitter.com/search?q=%22ANV+2YEARS+SECRET+LOVE%22",
          "tweetVolume": null
        },
        {
          "name": "राष्ट्रीय प्रेस",
          "query": "%22%E0%A4%B0%E0%A4%BE%E0%A4%B7%E0%A5%8D%E0%A4%9F%E0%A5%8D%E0%A4%B0%E0%A5%80%E0%A4%AF+%E0%A4%AA%E0%A5%8D%E0%A4%B0%E0%A5%87%E0%A4%B8%22",
          "url": "http://twitter.com/search?q=%22%E0%A4%B0%E0%A4%BE%E0%A4%B7%E0%A5%8D%E0%A4%9F%E0%A5%8D%E0%A4%B0%E0%A5%80%E0%A4%AF+%E0%A4%AA%E0%A5%8D%E0%A4%B0%E0%A5%87%E0%A4%B8%22",
          "tweetVolume": null
        },
        {
          "name": "Pengawas Sekolah",
          "query": "%22Pengawas+Sekolah%22",
          "url": "http://twitter.com/search?q=%22Pengawas+Sekolah%22",
          "tweetVolume": null
        },
        {
          "name": "Mason McCormick",
          "query": "%22Mason+McCormick%22",
          "url": "http://twitter.com/search?q=%22Mason+McCormick%22",
          "tweetVolume": null
        },
        {
          "name": "Courtney",
          "query": "Courtney",
          "url": "http://twitter.com/search?q=Courtney",
          "tweetVolume": null
        },
        {
          "name": "Mendoza",
          "query": "Mendoza",
          "url": "http://twitter.com/search?q=Mendoza",
          "tweetVolume": null
        },
        {
          "name": "Kerjasama Indonesia Norwegia",
          "query": "%22Kerjasama+Indonesia+Norwegia%22",
          "url": "http://twitter.com/search?q=%22Kerjasama+Indonesia+Norwegia%22",
          "tweetVolume": null
        },
        {
          "name": "Drew Sample",
          "query": "%22Drew+Sample%22",
          "url": "http://twitter.com/search?q=%22Drew+Sample%22",
          "tweetVolume": null
        },
        {
          "name": "England",
          "query": "England",
          "url": "http://twitter.com/search?q=England",
          "tweetVolume": null
        },
        {
          "name": "Ja'Marr Chase",
          "query": "%22Ja%27Marr+Chase%22",
          "url": "http://twitter.com/search?q=%22Ja%27Marr+Chase%22",
          "tweetVolume": null
        },
        {
          "name": "Bosa",
          "query": "Bosa",
          "url": "http://twitter.com/search?q=Bosa",
          "tweetVolume": null
        },
        {
          "name": "アチーブ",
          "query": "%E3%82%A2%E3%83%81%E3%83%BC%E3%83%96",
          "url": "http://twitter.com/search?q=%E3%82%A2%E3%83%81%E3%83%BC%E3%83%96",
          "tweetVolume": null
        },
        {
          "name": "Dak Prescott",
          "query": "%22Dak+Prescott%22",
          "url": "http://twitter.com/search?q=%22Dak+Prescott%22",
          "tweetVolume": null
        },
        {
          "name": "Critical Health",
          "query": "%22Critical+Health%22",
          "url": "http://twitter.com/search?q=%22Critical+Health%22",
          "tweetVolume": null
        },
        {
          "name": "Drew Lock",
          "query": "%22Drew+Lock%22",
          "url": "http://twitter.com/search?q=%22Drew+Lock%22",
          "tweetVolume": null
        },
        {
          "name": "Packers",
          "query": "Packers",
          "url": "http://twitter.com/search?q=Packers",
          "tweetVolume": null
        },
        {
          "name": "Collinsworth",
          "query": "Collinsworth",
          "url": "http://twitter.com/search?q=Collinsworth",
          "tweetVolume": null
        },
        {
          "name": "Seahawks",
          "query": "Seahawks",
          "url": "http://twitter.com/search?q=Seahawks",
          "tweetVolume": null
        },
        {
          "name": "Browns",
          "query": "Browns",
          "url": "http://twitter.com/search?q=Browns",
          "tweetVolume": null
        },
        {
          "name": "Spain",
          "query": "Spain",
          "url": "http://twitter.com/search?q=Spain",
          "tweetVolume": null
        },
        {
          "name": "Peñarol",
          "query": "Pe%C3%B1arol",
          "url": "http://twitter.com/search?q=Pe%C3%B1arol",
          "tweetVolume": null
        }
      ]
    }
  }
}

Billing

With the current configuration, each successful request costs 1 credit.

Every successful request, including empty results, is settled at the current database-configured rate. Failures are free. Sufficient balance is required before querying; insufficient balance during concurrent settlement returns 402 without delivering unsettled results. URL parsing adds no separate charge.

Status codes and errors

HTTPMeaning
200Success, including empty results
400Invalid JSON or parameters
401Invalid authentication
402Insufficient credits
429Rate limit; wait for Retry-After
502Data request failed
503API or pricing not configured
{"code":"invalid_params","message":"Invalid parameter"}