> For the complete documentation index, see [llms.txt](https://twitterscore.gitbook.io/twitterscore/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://twitterscore.gitbook.io/twitterscore/developers/api-documentation.md).
# API Documentation
By utilizing the TwitterScore API, you have the ability to access and leverage any information from the platform to your advantage. The limits on requests are based on your subscription plan.
**USERNAME** = username of X (Twitter) account.
**API\_KEY** = TwitterScore API key.
**TWITTER\_ID** = X (Twitter) ID. You can get from 1 request.
**Api Guide:**
**You can use either username or twitter id in any query.**
1. **Get Twitter Score.**
`https://twitterscore.io/api/v1/get_twitter_score?api_key=API_KEY&username=USERNAME`
*Answer Data: (Username, Twitter\_id, Twitter Score)*
***
2. **Twitter Score bulk check.**
`https://twitterscore.io/api/v1/bulk_scores_check?api_key=API_KEY&ids=IDS&size=50`
*Answer Data: (Twitter ID, U*sername*, Twitter Url, Twitter Score)*
***
3. **Get account info.**
`https://twitterscore.io/api/v1/get_twitter_info?api_key=API_KEY&twitter_id=TWITTER_ID`
*Answer Data: (Username, Name, Description, Followers Count, PFP Link)*
***
4. **Get how much score changed for a week/month.**
`https://twitterscore.io/api/v1/get_twitter_scores_diff?api_key=API_KEY&twitter_id=TWITTER_ID`
*Answer Data: (Twitter score changed for a week, for a month)*
***
5. **Get how much followers count changed for a week / month.**
`https://twitterscore.io/api/v1/get_followers_diff?api_key=API_KEY&twitter_id=TWITTER_ID`
*Answer Data: (Followers count diff for a week and for a month, with reference*\
*dates.)*
***
6. **Get history of followers count (for 3 / 7 / 30 / 180 / 360 / all days).**
Default - 30 days
`https://twitterscore.io/api/v1/followers_count_history?api_key=API_KEY&twitter_id=TWITTER_ID`
Custom - 3/7/30/180/360/all days
`https://twitterscore.io/api/v1/followers_count_history?api_key=API_KEY&twitter_id=TWITTER_ID&period=1w`
*Or*
`https://twitterscore.io/api/v1/followers_count_history?api_key=API_KEY&twitter_id=TWITTER_ID&period=all&page=PAGE`
*Answer Data: (Returns the number of subscribers for each day. You can read page by page by passing parameters: page)*
***
7. **Get list of all categories**
`https://twitterscore.io/api/v1/get_categories?api_key=API_KEY`
*Answer Data: (*Returns a list of all categories: id, name*)*
***
8. **Get list of all tags and tag's category**
`https://twitterscore.io/api/v1/get_tags?api_key=API_KEY`
*Answer Data: (Returns a list of all tags with their category)*
***
9. **Get number of followers in each category**
`https://twitterscore.io/api/v1/get_categorized_followers_count?username=USERNAME&api_key=API_KEY`
*Answer Data: (Number of followers in each category)*
***
10. **Get the number of tagged subscribers in each category**
`https://twitterscore.io/api/v1/get_tagged_followers_count?api_key=API_KEY&username=USERNAME`
*Answer Data: (Returns the number of tagged subscribers in each category)*
***
11. **Get paginated** **list of followers (filtered by size, tag, category, tag 's category).**
**Get list of all followers**
`https://twitterscore.io/api/v1/get_followers?api_key=API_KEY&twitter_id=TWITTER_ID`
*You can read page by page by passing parameters: page and size:*
`https://twitterscore.io/api/v1/get_followers?API_KEY&twitter_id=TWITTER_ID&size=SIZE&page=PAGE`
*Answer Data: (Returns a list of all followers sorted by twitter score)*
**Get list of followers filtred by category**
`https://twitterscore.io/api/v1/get_followers?API_KEY&twitter_id=TWITTER_ID&category_id=CATEGORY_ID`
*Answer Data: (Returns a list of all followers in specified category sorted by twitter score. You can read page by page by passing parameters: page and size)*
**Get list of followers filtred by tag**
`https://twitterscore.io/api/v1/get_followers?API_KEY&twitter_id=TWITTER_ID&tag_id=TAG_ID`
*Answer Data: (Returns a list of all followers with specified tag sorted by twitter score. You can read page by page by passing parameters: page and size)*
**Get list of followers filtred by tag 's category**
`https://twitterscore.io/api/v1/get_followers?API_KEY&twitter_id=TWITTER_ID&tag_category_id=TAG_CATEGORY_ID`
*Answer Data: (Returns a list of all followers in specified tag's category sorted by twitter score. You can read page by page by passing parameters: page and size)*
***
12. **Get friendship History.**
**Get friendship History - followed**
`https://twitterscore.io/api/v1/friendshipHistory/followed?username=USERNAME&api_key=API_KEY&date=DATE&tag_ids=TAG_IDS&size=SIZE`
*Answer Data: (Returns a list of followed accounts on a specified date. Could be filtred by tag id.)*
**Get friendship History - following**
`https://twitterscore.io/api/v1/friendshipHistory/following?username=USERNAME&api_key=API_KEY&date=DATE&tag_ids=TAG_IDS&size=SIZE`
*Answer Data: (Returns a list of following accounts on a specified date. Could be filtred by tag id.)*
***
14. **Check your API limits.**
`https://twitterscore.io/api/v1/limits?api_key=API_KEY`
*Answer Data: (Returns a stats of your API subscription.)*
***
**NEW ENDPOINTS 🔥**
***
15. **Get aggregated TwitterScore sum of smart followers.**
`https://twitterscore.io/api/v1/get_followers_score_sum?api_key=API_KEY&twitter_id=TWITTER_ID`
*Answer Data: (Returns the sum of TwitterScore across all smart followers of the account*\
*(filterable by tags / categories), plus basic profile info.)*
***
16. **Get top accounts by mentions over a period (**SMART MENTIONS PAGE**).**
`https://twitterscore.io/api/v1/get_smart_mentions?api_key=API_KEY`
*Answer Data: (Returns top accounts ranked by how often they were mentioned over the selected period (1/7/30 days). Same data that powers the /smart-mentions/ page. Each row includes mention totals, unique mentioners count, deltas vs previous period, top\_mentioner snapshot and mentioners\_list preview.)*
***
17. **Get list of unique mentioners for an account.**
`https://twitterscore.io/api/v1/get_mentioners?api_key=API_KEY&twitter_id=TWITTER_ID`
*Answer Data: (Returns account profile info + list of unique accounts that mentioned it over*\
*the selected period. Corresponds to the "Unique Mentions" column on the*\
*Smart Mentions page.)*
***
18. **Get smart mentions feed for an account.**
`https://twitterscore.io/api/v1/get_mentions_feed?api_key=API_KEY&username=USERNAME`
*Answer Data: (*Returns a paginated feed of tweets that mention the specified account.\
Each mention includes post text, engagement metrics (favorites/retweets/replies/\
views), author info with twitter\_score + categories + tags, and attached media/\
URLs.*)*
***
19. **Get trending accounts.**
`https://twitterscore.io/api/v1/get_trending?api_key=API_KEY`
*Answer Data: (Returns the list of trending accounts over the selected period (3/7/30*\
*days) with follower and twitter\_score deltas. Same data that powers the*\
*/trending/ page.)*
***
20. **Get top researched accounts (last 24 hours).**
`https://twitterscore.io/api/v1/get_top_researched?api_key=API_KEY`
*Answer Data: (Returns the top 10 crypto accounts by search/lookup activity over the last*\
*24 hours. Same data that powers the /topResearched/ page.)*
***
21. **Get tokenless projects.**
`https://twitterscore.io/api/v1/get_tokenless?api_key=API_KEY`
*Answer Data: (Returns a paginated list of tokenless crypto accounts ranked by followers growth. Same data that powers the Airdrop page. Each item includes twitter\_score, current/previous follower counts with delta.)*
***
22. **Get Smart Follows accounts.**
`https://twitterscore.io/api/v1/get_alpha?api_key=API_KEY`
*Answer Data: (*Returns a paginated list of accounts ranked by new alpha followers gained over a configurable period. Same data that powers the Alpha page.*)*
***
**DEPRECATED**
***
* **Get top 5 followers by score.**
`https://twitterscore.io/api/v1/get_twitter_top_followers?api_key=API_KEY&twitter_id=TWITTER_ID`
*Answer Data: (Top 5 followers by score, usernames, names, score, followers count, PFP Link)*
{% hint style="info" %}
**This request is deprecated. It can be completely replaced by request - Get paginated** **list of followers**
{% endhint %}
***
* **Get top followers paginate**
`https://twitterscore.io/api/v1/top_followers_paginate?username=USERNAME&api_key=API_KEY&size=SIZE&page=PAGE`
*Answer Data: (Paginated list of top followers)*
{% hint style="info" %}
**This request is deprecated. It can be completely replaced by request - Get paginated** **list of followers**
{% endhint %}
***
{% hint style="info" %}
**If you can't find the feature you need here, feel free to** [**contact us**](https://t.me/TwitterScore_collab)**. We'll work together to find a solution for your problem.**
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://twitterscore.gitbook.io/twitterscore/developers/api-documentation.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.