Comparing Twitter API’s Tweet counts endpoints
The v2 Tweet counts endpoint will eventually replace the premium v1.1 Search API’s counts endpoint, and enterprise Search API’s counts endpoint. If you have code, apps, or tools that use an older version of a Tweet counts endpoint and are considering migrating to the newer Twitter API v2 endpoints, then this guide is for you.
This page contains two comparison tables:
Recent Tweet counts comparison
The older premium and enterprise versions of the Tweet counts endpoints allow you to pull counts for either 30 days or from the full-archive. Therefore, the v2 recent Tweet counts endpoint, which looks at a 7 day time period, is not a direct replacement for either of the aforementioned endpoints.
However, to help with comparisons, we will look at how the v2 recent Tweet counts endpoint compares to the premium and enterprise 30-day endpoint.
The following table compares the various types of recent Tweet counts endpoints:
| Description | Premium v1.1 | Enterprise | Twitter API v2 |
| Host domain | https://api.twitter.com | https://gnip-api.twitter.com | https://api.twitter.com |
| Endpoint path | /1.1/tweets/search/30day/:environment/counts.json | /search/30day/accounts/:account_name/:label/counts.json | /2/tweets/counts/recent |
| Authentication | OAuth 2.0 Bearer Token | Basic authentication | OAuth 2.0 Bearer Token |
| Timestamp format | YYYYMMDDhhmm | YYYYMMDDhhmm | YYYY-MM-DDTHH:mm:ssZ ISO 8601 / RFC 3339 |
| Returns counts of Tweets that are no older than | 31 days | 31 days | 7 days |
| HTTP methods supported | GET | GET | GET |
| Default request rate limits | 60 requests per 1 minute, aggregated across search data and counts requests |
20 requests per 1 sec, aggregated across search data and counts requests The per minute rate limit will vary by partner as specified in your contract. |
180 requests per 15 min per user 450 requests per 15 min per App |
| Supports filtering using annotations | ✔ | ||
| Supports filtering using conversation_id | ✔ | ||
| JSON key name for Tweet data array | results | results | data |
| Time granularity | Day, hour, or minute | Day, hour, or minute | Day, hour, or minute |
| Timezone | UTC | UTC | UTC |
| Request parameters for selecting time period | fromDate toDate |
fromDate toDate |
start_time end_time |
| Request parameters for navigating by Tweet ID | since_id until_id |
||
| Requires the use of credentials from a developer App associated with a project | ✔ |
Full-archive Tweet counts comparison
The following table compares the various types of full-archive search endpoints:
| Description | Premium v1.1 | Enterprise | Twitter API v2 |
|---|---|---|---|
| Host domain | https://api.twitter.com | https://gnip-api.twitter.com | https://api.twitter.com |
| Endpoint path | /1.1/tweets/search/fullarchive/:label/counts.json | /search/fullarchive/accounts/:account_name/:label/counts | /2/tweets/counts/all |
| Authentication | OAuth 2.0 Bearer Token | Basic auth | OAuth 2.0 Bearer Token |
| Timestamp format | YYYYMMDDHHMM | YYYYMMDDHHMM | YYYY-MM-DDTHH:mm:ssZ ISO 8601 / RFC 3339 |
| Returns Tweet counts that are no older than | The full archive since March 2006 | The full archive since March 2006 | The full archive since March 2006 |
| HTTP methods supported | GET POST |
GET POST |
GET |
| Default request rate limits | Paid premium 60 requests per 1 min, aggregated across search and counts endpoints Sandbox premium 30 requests per 1 min, aggregated across search and counts endpoints Both 10 requests per 1 sec, aggregated across search and counts endpoints |
The per minute rate limit will vary by partner as specified in your contract. 20 requests per sec |
300 requests per 15 min per App 1 request per 1 sec per App |
| Granularity | Day, hour, minute | Day, hour, minute | Day, hour, minute |
| Supports filtering using annotations | ✔ | ||
| Supports filtering using conversation_id | ✔ | ||
| JSON key name for Tweet data array | results | results | data |
| Request parameters for selecting time period | fromDate toDate |
fromDate toDate |
start_time end_time |
| Request parameters for navigating by Tweet ID | since_id until_id |
||
| JSON key name for pagination | next | next | meta.next_token |
| Request parameter for pagination | next_token | next_token | next_token or pagination_token |
| Timezone | UTC | UTC | UTC |
| Requires the use of credentials from a developer App associated with a Project that has Academic Research access | ✔ |
Filtering operator comparison
The three different versions (premium, enterprise, and v2) of Tweet counts differ in which operators are available, and also have varying levels of operator availability within each version, which are explained below.
Premium
- Sandbox and paid: These operators are available to all premium users.
- Pain only: These operators are only available to those users that are using a paid tier of premium.
Enterprise
- There are no sub-tiers of enterprise operators. All enterprise operators are available to all enterprise users.
Twitter API v2
- Core: These operators are available to any v2 user.
- Advanced: These operators are only available to users that have been approved for Academic Research access.
You can learn more about each of these sets of operators in their respective guides:
Now that we understand these different operator levels within premium and Twitter API v2, here is the table that maps out operator availability for Tweet counts (note that if the cell is left blank, the operator is not available):
| Premium | Enterprise | v2 | |
|---|---|---|---|
| keyword | Sandbox and paid | Available | Core |
| emoji | Sandbox and paid | Available | Core |
| “exact phrase” | Sandbox and paid | Available | Core |
| # | Sandbox and paid | Available | Core |
| $ | Available | Advanced | |
| @ | Sandbox and paid | Available | Core |
| from: | Sandbox and paid | Available | Core |
| to: | Sandbox and paid | Available | Core |
| url: | Sandbox and paid | Available | Core |
| retweets_of: | Sandbox and paid | Available | Core |
| context: | Core | ||
| entity: | Core - Only available with recent search | ||
| conversation_id: | Core | ||
| place: | Sandbox and paid | Available | Advanced |
| place_country: | Sandbox and paid | Available | Advanced |
| point_radius: | Sandbox and paid | Available | Advanced |
| bounding_box: | Sandbox and paid | Available | Advanced |
| is:retweet | Paid only | Available | Core |
| is:reply | Paid only | Available | Core |
| is:quote | Sandbox and paid | Available | Core |
| is:verified | Paid only | Available | Core |
| -is:nullcast | Available | Advanced | |
| has:hashtags | Paid only | Available | Core |
| has:cashtags | Available | Advanced | |
| has:links | Sandbox and paid | Available | Core |
| has:mentions | Sandbox and paid | Available | Core |
| has:media | Sandbox and paid | Available | Core |
| has:images | Sandbox and paid | Available | Core |
| has:videos | Sandbox and paid | Available | Core |
| has:geo | Paid only | Available | Advanced |
| lang: | Sandbox and paid | Available | Core |
| list: | Advanced | ||
| has:profile_geo | Paid only | Available | |
| profile_country | Paid only | Available | |
| profile_locality | Paid only | Available | |
| profile_region | Paid only | Available | |
| proximity | Available |