Please note: We have released a new version of search Posts and Post counts in X API v2. We encourage you to review what’s new with X API v2. These endpoints have been updated to include Post edit metadata. Learn more about these metadata on the “Edit Posts” fundamentals page.
Enterprise
The enterprise APIs are available within our managed access levels only. To use these APIs, you must first set up an account with our enterprise sales team. To learn more see HERE.
You can view all of the X API search Post offerings HERE.
There are two enterprise search APIs:
Matching on Post contents: | Matching on accounts of interest: | Post attributes: | Geospatial operators: |
* keyword * “quoted phrase” * “keyword1 keyword2”~N * # * @ * $ * url: * lang: | * from: * to: * retweets_of: | * is:retweet * has:mentions * has:hashtags * has:media * has:videos * has:images * has:links * has:symbols * is:verified * -is:nullcast (negation only operator) | * bounding_box:[west_long south_lat east_long north_lat] * point_radius:[lon lat radius] * has:geo * place: * place_country: * has:profile_geo * profile_country: * profile_region: * profile_locality: |
from:
and lang:
operators to find Posts originating from @XDevelopers in English. For more operators click here.
<USERNAME>
e.g. email@domain.com
<ACCOUNT-NAME>
e.g. john-doe
<LABEL>
e.g. prod
"fromDate":"201811010000", "toDate":"201811122359"
day
.
<USERNAME>
e.g. email@domain.com
<ACCOUNT-NAME>
e.g. john-doe
<LABEL>
e.g. prod
"fromDate":"201811010000", "toDate":"201811122359"
from:
and lang:
operators to find Posts originating from @XDevelopers in English. For more operators click here.
<USERNAME>
e.g. email@domain.com
<ACCOUNT-NAME>
e.g. john-doe
<LABEL>
e.g. prod
"fromDate":"201802010000", "toDate":"201802282359"
day
.
<USERNAME>
e.g. email@domain.com
<ACCOUNT-NAME>
e.g. john-doe
<LABEL>
e.g. prod
"fromDate":"201802010000", "toDate":"201802282359"
Operator | Description |
---|---|
keyword | Matches a tokenized keyword within the body or urls of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters. For example, a Post with the text “I like coca-cola” would be split into the following tokens: I, like, coca, cola. These tokens would then be compared to the keyword string used in your rule. To match strings containing punctuation (for example, coca-cola), symbol, or separator characters, you must use a quoted exact match as described below. Note: With the Search API, accented and special characters are normalized to standard latin characters, which can change meanings in foreign languages or return unexpected results: For example, “músic” will match “music” and vice versa. For example, common phrases like “Feliz Año Nuevo!” in Spanish, would be indexed as “Feliz Ano Nuevo”, which changes the meaning of the phrase. Note: This operator will match on both URLs and unwound URLs within a Post. |
emoji | Matches an emoji within the body of a Post. Emojis are a tokenized match, meaning that your emoji will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol/emoji, and separator Unicode basic plane characters. For example, a Post with the text “I like ” would be split into the following tokens: I, like, . These tokens would then be compared to the emoji used in your rule. Note that if an emoji has a variant, you must use “quotations” to add to a rule. |
”exact phrase match” | Matches the tokenized and ordered phrase within the body or urls of a Post. This is a tokenized match, meaning that your keyword string will be matched against the tokenized text of the Post body – tokenization is based on punctuation, symbol, and separator Unicode basic plane characters. Note: Punctuation is not tokenized and is instead treated as whitespace. For example, quoted “#hashtag” will match “hashtag” but not #hashtag (use the hashtag # operator without quotes to match on actual hashtags. For example, quoted “cashtag (use the cashtag $ operator without quotes to match on actual cashtags. For example, “Love Snow” will match “#love #snow” For example, “#Love #Snow” will match “love snow” Note: This operator will match on both URLs and unwound URLs within a Post. |
”keyword1 keyword2”~N | Commonly referred to as a proximity operator, this matches a Post where the keywords are no more than N tokens from each other. If the keywords are in the opposite order, they can not be more than N-2 tokens from each other. Can have any number of keywords in quotes. N cannot be greater than 6. Note that this operator is only available in the enterprise search APIs. |
from: | Matches any Post from a specific user. The value must be the user’s X numeric Account ID or username (excluding the @ character). See HERE or HERE for methods for looking up numeric X Account IDs. |
to: | Matches any Post that is in reply to a particular user. The value must be the user’s numeric Account ID or username (excluding the @ character). See HERE for methods for looking up numeric X Account IDs. |
url: | Performs a tokenized (keyword/phrase) match on the expanded URLs of a Post (similar to url_contains). Tokens and phrases containing punctuation or special characters should be double-quoted. For example, url:“/developer”. While generally not recommended, if you want to match on a specific protocol, enclose in double-quotes: url:“https://developer.x.com”. Note: When using PowerTrack or Historical PowerTrack, this operator will match on URLs contained within the original Post of a Quote Post. For example, if your rule includes url:“developer.x.com”, and a Post contains that URL, any Quote Tweets of that Post will be included in the results. This is not the case when using the Search API. |
# | Matches any Post with the given hashtag. This operator performs an exact match, NOT a tokenized match, meaning the rule “2016” will match posts with the exact hashtag “2016”, but not those with the hashtag “2016election” Note: that the hashtag operator relies on X’s entity extraction to match hashtags, rather than extracting the hashtag from the body itself. See HERE for more information on X Entities JSON attributes. |
@ | Matches any Post that mentions the given username. The to: operator returns a subset match of the @mention operator. |
$ | Matches any Post that contains the specified ‘cashtag’ (where the leading character of the token is the ‘$’ character). Note that the cashtag operator relies on X’s ‘symbols’ entity extraction to match cashtags, rather than trying to extract the cashtag from the body itself. See HERE for more information on X Entities JSON attributes. Note that this operator is only available in the enterprise search APIs. |
retweets_of: | Available alias: retweets_of_user: Matches Posts that are retweets of a specified user. Accepts both usernames and numeric X Account IDs (NOT Post status IDs).See HERE for methods for looking up numeric X Account IDs. |
lang: | Matches Posts that have been classified by X as being of a particular language (if, and only if, the post has been classified). It is important to note that each Post is currently only classified as being of one language, so AND’ing together multiple languages will yield no results. Note: if no language classification can be made the provided result is ‘und’ (for undefined). The list below represents the current supported languages and their corresponding BCP 47 language indentifier: |
Amharic: am | German: de | Malayalam: ml | Slovak: sk |
Arabic: ar | Greek: el | Maldivian: dv | Slovenian: sl |
Armenian: hy | Gujarati: gu | Marathi: mr | Sorani Kurdish: ckb |
Basque: eu | Haitian Creole: ht | Nepali: ne | Spanish: es |
Bengali: bn | Hebrew: iw | Norwegian: no | Swedish: sv |
Bosnian: bs | Hindi: hi | Oriya: or | Tagalog: tl |
Bulgarian: bg | Latinized Hindi: hi-Latn | Panjabi: pa | Tamil: ta |
Burmese: my | Hungarian: hu | Pashto: ps | Telugu: te |
Croatian: hr | Icelandic: is | Persian: fa | Thai: th |
Catalan: ca | Indonesian: in | Polish: pl | Tibetan: bo |
Czech: cs | Italian: it | Portuguese: pt | Traditional Chinese: zh-TW |
Danish: da | Japanese: ja | Romanian: ro | Turkish: tr |
Dutch: nl | Kannada: kn | Russian: ru | Ukrainian: uk |
English: en | Khmer: km | Serbian: sr | Urdu: ur |
Estonian: et | Korean: ko | Simplified Chinese: zh-CN | Uyghur: ug |
Finnish: fi | Lao: lo | Sindhi: sd | Vietnamese: vi |
French: fr | Latvian: lv | Sinhala: si | Welsh: cy |
Georgian: ka | Lithuanian: lt |
place: | Matches Posts tagged with the specified location or X place ID (see examples). Multi-word place names (“New York City”, “Palo Alto”) should be enclosed in quotes. Note: See the GET geo/search public API endpoint for how to obtain X place IDs. Note: This operator will not match on Retweets, since Retweet’s places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. |
place_country: | Matches Posts where the country code associated with a tagged place matches the given ISO alpha-2 character code. Valid ISO codes can be found here: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 Note: This operator will not match on Retweets, since Retweet’s places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. |
point_radius:[lon lat radius] | Matches against the Exact Location (x,y) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region. * Units of radius supported are miles (mi) and kilometers (km). * Radius must be less than 25mi. * Longitude is in the range of ±180 * Latitude is in the range of ±90 * All coordinates are in decimal degrees. * Rule arguments are contained with brackets, space delimited. Note: This operator will not match on Retweets, since Retweet’s places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. |
bounding_box:[west_long south_lat east_long north_lat] | Available alias: geo_bounding_box: Matches against the Exact Location (long, lat) of the Post when present, and in X, against a “Place” geo polygon, where the Place is fully contained within the defined region. * west_long south_lat represent the southwest corner of the bounding box where west-long is the longitude of that point, and south_lat is the latitude. * east_long and north_lat represent the northeast corner of the bounding box, where east_long is the longitude of that point, and north_lat is the latitude. * Width and height of the bounding box must be less than 25mi * Longitude is in the range of ±180 * Latitude is in the range of ±90 * All coordinates are in decimal degrees. * Rule arguments are contained with brackets, space delimited. Note: This operator will not match on Retweets, since Retweet’s places are attached to the original Post. It will also not match on places attached to the original Post of a Quote Tweet. |
profile_country: | Exact match on the “countryCode” field from the “address” object in the Profile Geo enrichment. Uses a normalized set of two-letter country codes, based on ISO-3166-1-alpha-2 specification. This operator is provided in lieu of an operator for “country” field from the “address” object to be concise. |
profile_region: | Matches on the “region” field from the “address” object in the Profile Geo enrichment. This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\/two”. Use double quotes to match substrings that contain whitespace or punctuation. |
profile_locality: | Matches on the “locality” field from the “address” object in the Profile Geo enrichment. This is an exact full string match. It is not necessary to escape characters with a backslash. For example, if matching something with a slash, use “one/two”, not “one\/two”. Use double quotes to match substrings that contain whitespace or punctuation. |
has:geo | Matches Posts that have Post-specific geo location data provided from X. This can be either “geo” lat-long coordinate, or a “location” in the form of a X “Place”, with corresponding display name, geo polygon, and other fields. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
has:profile_geo | Available alias: has:derived_user_geo Matches Posts that have any Profile Geo metadata, regardless of the actual value. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
has:links | This operators matches Posts which contain links in the message body. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
is:retweet | Deliver only explicit retweets that match a rule. Can also be negated to exclude retweets that match a rule from delivery and only original content is delivered. This operator looks only for true Retweets, which use X’s retweet functionality. Quoted Tweets and Modified Posst which do not use X’s retweet functionality will not be matched by this operator. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
is:reply | An operator to filter Posts based on whether they are or are not replies to Posts. Deliver only explicit replies that match a rule. Can also be negated to exclude replies that match a rule from delivery. Note that this operator is available for paid premium and enterprise search and is not available in Sandbox dev environments. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
is:quote | Delivers only Quote Tweets, or Posts that reference another Post, as identified by the “is_quote_status”:true in Post payloads. Can also be negated to exclude Quote Tweets. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
is:verified | Deliver only Posts where the author is “verified” by X. Can also be negated to exclude Posts where the author is verified. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
has:mentions | Matches Posts that mention another X user. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
has:hashtags | Matches Posts that contain a hashtag. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
has:media | Available alias: has:media_link Matches Posts that contain a media url classified by X. For example, pic.x.com. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
has:images | Matches Posts that contain a media url classified by X. For example, pic.x.com. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
has:videos | Available alias: has:video_link Matches Posts that contain native X videos, uploaded directly to X. This will not match on videos created with Vine, Periscope, or Posts with links to other video hosting sites. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
has:symbols | Matches Posts that contain a cashtag symbol (with a leading ‘tag). Note that this operator is only available in the enterprise search APIs. Note: When using the Search API, this operator must be used in conjunction with other operators that don’t include is: or has: . |
to:
and in_reply_to_status_id:
PowerTrack Operators.
The details provided here were generated using Full-Archive Search (a product of hundreds of searches). This timeline is not 100% complete or precise. If you identify another filtering/metadata “born on date” fundamental to your use-case, please let us know.
Note that the underlying Search index is subject to being rebuilt. Accordingly, these timeline details are subject to change.
lang:
. An example of Post metadata being backfilled while generating the Search index.has:mentions
begins matching.has:symbols
. slang).has:links
begins matching.has:hashtags
begins matching.reply_to_status_id:
begins matching.is:retweet
. Note that this Operator starts matching with the ‘beta’ release of official Retweets and its “Via @’ pattern. During this beta period, the Post verb is ‘post’ and the original Post is not included in the payload.has:geo
, bounding_box:
and point_radius:
geo Operators begin matching.has:videos
(Until February 2015, this Operator matches on Posts with links to select video hosting sites such as youtube.com, vimeo.com, and vivo.com).has:media
and has:images
begin matching. Native photos officially announced August 9, 2010.has:videos
matches on ‘native’ X videos.has:profile_geo
, profile_country:
, profile_region:
, profile_locality:
Profile Geo Operators begin matching.place_country:
and place:
Post geo Operators begin matching.has:images
Operator, you will not have any matches for periods before July 2011. That is because that Operator matches on native photos (attached to a Post using the X user-interface). For a more complete data set of photo-sharing Posts, filters for before July 2011 would need to contain rule clauses that match on common URLs for photo hosting._is:retweet_
Operator enables users to either include or exclude Retweets. Users of this Operator need to have two strategies for Retweet matching (or not matching) for data before August 2009. Before August 2009, the Post message itself needs to be checked, using exact phrase matching, for matches on the “@RT ” pattern (Actually, if you are filtering on Retweets from between May-August 2009, the “Via @” pattern should be included). For periods after August 2009, the is:retweet Operator is available.
has:geo
, bounding_box:
and point_radius:
place_country:
and place:
bio_location:
Operator is available which can be used to match on non-normalized user input.
has:links
has:images
and has:media
url:
with the Expanded URLs enrichment As early as September 2006 (url:"spotify.com" OR url:gnip OR url:microsoft OR url:google OR url:youtube)
matches http://x.com/Adam/statuses/16602, even though there is no urls[] metadata in twitter_entities and gnip objects. “youtube.com” is an example of message content that, without any urls[] metadata, matches url:youtube.has:videos
for native videos. Between 2010/08/28 and 2015/02/10, this Operator matches on Posts with links to select video hosting sites such as youtube.com, vimeo.com, and vivo.com.url_title:
and url_description:
, based on the Enhanced URLs enrichment, generally available. First Enhanced URL metadata began appearing in December 2014.The number of Posts I receive with the data endpoint doesn't match the number of Posts identified by the counts endpoint. Why is this the case?
I didn't receive a Post that should match my query. Why?
My query matched a Post but includes a keyword that I negated. Why is this happening?
Are there any libraries that I can use to get started using the Search Post APIs?
Will I ever receive less volume of Posts than the value I set as the `maxResults` in my request to the data endpoint?
maxResults
or after 30 days.For example, if you have 800 Posts in a given 30 day period, you will have to make two requests to pull the complete results; because the maximum number of Posts that can be returned per request is 500 (maxResults
). And if you just have 400 Posts in month one, and then 100 Posts in month two, you will also have to use two requests to pull the full results; because pagination takes place after a period of 30 days even if the first request returns less than the specified maxResults
Posts.In what order are the matching Posts returned?
fromDate
initially requested.How do Edit Posts impact my usage and billing?
Enterprise
I'm interested in learning more about the pricing of the enterprise Search Post API and in applying for this offering. How can I do this?
How do I build a rule set that matches my use case?
I have exceeded my request caps/limits for the month, but I need to access more data - what can I do?
buckets
field can only be used with the counts endpoint, not the data endpoint):product
:account_name
and :label
fields are correct. You can find your :label
field in the GNIP Console (enterprise customers only).https://gnip-api.x.com/search/
.
Method | Description |
---|---|
POST /search/:product/accounts/:account_name/:label | Retrieve Tweets from the past 30 days that match the specified PowerTrack rule. |
POST /search/:product/accounts/:account_name/:label/counts | Retrieve the number of Tweets from the past 30 days that match the specified PowerTrack rule. |
:product
indicates the search endpoint you are making requests to, either 30day
or fullarchive
.:account_name
is the (case-sensitive) name associated with your account, as displayed at console.gnip.com:label
is the (case-sensitive) label associated with your search endpoint, as displayed at console.gnip.com:product
, :account_name
, and :label
. To use these examples, be sure to update the URLs with your details.
fromDate
and toDate
parameters, you can request any time period that the API supports. The 30-Day search API provides Tweets from the most recent 31 days (even though referred to as the ‘30-Day’ API, it makes 31 days available to enable users to make complete-month requests). The Full-Archive search API provides Tweets back to the very first tweet (March 21, 2006). However, a single response will be limited to the lesser of your specified ‘maxResults’ or 31 days. If matching data or your time range exceeds your specified maxResults or 31 days, you will receive a ‘next’ token which you should use to paginate through the remainder of your specified time range.
For example, say you are using Full-Archive search and want all Tweets matching your query from January 1, 2017 to June 30, 2017. You will specify that full six-month time period in your request using the fromDate
and toDate
parameters. The search API will respond with the first ‘page’ of Tweets, with the number of Tweets matching your maxResults
parameter (which defaults to 100). Assuming there are more Tweets (and there most likely will be more), the API will also provide a ‘next’ token that enables you to make a request for the next ‘page’ of data. This process is repeated until the API does not return a ‘next’ token. See the next section for more details.
maxResults
parameter defaults to 100 and can be set to a range of 10-500. If your query matches more Tweets than the ‘maxResults’ parameter used in the request, the response will include a ‘next’ token (as a root-level JSON attribute). This ‘next’ token is used in the subsequent request to retrieve the next portion of the matching Tweets for that query (i.e. the next ‘page”). Next tokens will continue to be provided until you have reached the last ‘page’ of results for that query when no ‘next’ token is provided.
To request the next ‘page’ of data, you must make the exact same query as the original, including query
, toDate
, and fromDate
parameters, if used, and also include a ‘next’ request parameter set to the value from the previous response. This can be utilized with either a GET or POST request. However, the ‘next’ parameter must be URL encoded in the case of a GET request.
You can continue to pass in the ‘next’ element from your previous query until you have received all Tweets from the time period covered by your query. When you receive a response that does not include a ‘next’ element, it means that you have reached the last page and no additional data is available for the specified query and time range.
Parameters | Description | Required | Sample Value |
---|---|---|---|
query | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses). This parameter should include ALL portions of the PowerTrack rule, including all operators, and portions of the rule should not be separated into other parameters of the query. Note: Not all PowerTrack operators are supported. Supported Operators are listed HERE. | Yes | (snow OR cold OR blizzard) weather |
tag | Tags can be used to segregate rules and their matching data into different logical groups. If a rule tag is provided the rule tag is included in the ‘matching_rules’ attribute. It is recommended to assign rule-specific UUIDs to rule tags and maintain desired mappings on the client side. | No | 8HYG54ZGTU |
fromDate | The oldest UTC timestamp (back to 3/21/2006 with Full-Archive search) from which the Tweets will be provided. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute). Specified: Using only the fromDate with no toDate parameter will deliver results for the query going back in time from now( ) until the fromDate. Not Specified: If a fromDate is not specified, the API will deliver all of the results for 30 days prior to now( ) or the toDate (if specified). If neither the fromDate or toDate parameter is used, the API will deliver all results for the most recent 30 days, starting at the time of the request, going backwards. | No | 201207220000 |
toDate | The latest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in minute granularity and is not inclusive (i.e. 11:59 does not include the 59th minute of the hour). Specified: Using only the toDate with no fromDate parameter will deliver the most recent 30 days of data prior to the toDate. Not Specified: If a toDate is not specified, the API will deliver all of the results from now( ) for the query going back in time to the fromDate. If neither the fromDate or toDate parameter is used, the API will deliver all results for the entire 30-day index, starting at the time of the request, going backwards. | No | 201208220000 |
maxResults | The maximum number of search results to be returned by a request. A number between 10 and the system limit (currently 500). By default, a request response will return 100 results. | No | 500 |
next | This parameter is used to get the next ‘page’ of results as described HERE. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. | No | NTcxODIyMDMyODMwMjU1MTA0 |
Available Timeframe | 30-Day: last 31 days Full-Archive: March 21, 2006 - Present |
Query Format | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses). Note: Not all PowerTrack operators are supported. Refer to Available operators for a list of supported operators. |
Rate Limit | Partners will be rate limited at both minute and second granularity. The per minute rate limit will vary by partner as specified in your contract. However, these per-minute rate limits are not intended to be used in a single burst. Regardless of your per minute rate limit, all partners will be limited to a maximum of 20 requests per second, aggregated across all requests for data and/or counts. |
Compliance | All data delivered via the Full-Archive Search API is compliant at the time of delivery. |
Realtime Availability | Data is available in the index within 30 seconds of generation on the Twitter Platform |
/search/fullarchive/accounts/:account_name/:label/counts.json
This endpoint returns counts (data volumes) data for the specified query. If a time period is not specified the time parameters will default to the last 30 days. Data volumes are returned as a timestamped array on either daily, hourly (default), or by the minute.
Note: This functionality can also be accomplished using a GET request, instead of a POST, by encoding the parameters described below into the URL.
Parameters | Description | Required | Sample Value |
---|---|---|---|
query | The equivalent of one PowerTrack rule, with up to 2,048 characters (and no limits on the number of positive and negative clauses). This parameter should include ALL portions of the PowerTrack rule, including all operators, and portions of the rule should not be separated into other parameters of the query. Note: Not all PowerTrack operators are supported. Refer to Available operators for a list of supported operators. | Yes | (snow OR cold OR blizzard) weather |
fromDate | The oldest UTC timestamp (back to 3/21/2006) from which the Tweets will be provided. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute). Specified: Using only the fromDate with no toDate parameter, the API will deliver counts (data volumes) data for the query going back in time from now until the fromDate. If the fromDate is older than 31 days from now( ), you will receive a next token to page through your request. Not Specified: If a fromDate is not specified, the API will deliver counts (data volumes) for 30 days prior to now( ) or the toDate (if specified). If neither the fromDate or toDate parameter is used, the API will deliver counts (data volumes) for the most recent 30 days, starting at the time of the request, going backwards. | No | 201207220000 |
toDate | The latest, most recent UTC timestamp to which the Tweets will be provided. Timestamp is in minute granularity and is not inclusive (i.e. 11:59 does not include the 59th minute of the hour). Specified: Using only the toDate with no fromDate parameter will deliver the most recent counts (data volumes) for 30 days prior to the toDate. Not Specified: If a toDate is not specified, the API will deliver counts (data volumes) for the query going back in time to the fromDate. If the fromDate is more than 31 days from now( ), you will receive a next token to page through your request. If neither the fromDate or toDate parameter is used, the API will deliver counts (data volumes) for the most recent 30 days, starting at the time of the request, going backwards. | No | 201208220000 |
bucket | The unit of time for which count data will be provided. Count data can be returned for every day, hour or minute in the requested timeframe. By default, hourly counts will be provided. Options: ‘day’, ‘hour’, ‘minute’ | No | minute |
next | This parameter is used to get the next ‘page’ of results as described HERE. The value used with the parameter is pulled directly from the response provided by the API, and should not be modified. | No | NTcxODIyMDMyODMwMjU1MTA0 |
Available Timeframe | 30-Day: last 31 days Full-Archive: March 21, 2006 - Present |
Query Format | The equivalent of one PowerTrack rule, with up to 2,048 characters. Note: Not all PowerTrack operators are supported. Refer to Available operators for a list of supported operators. |
Rate Limit | Partners will be rate limited at both minute and second granularity. The per minute rate limit will vary by partner as specified in your contract. However, these per-minute rate limits are not intended to be used in a single burst. Regardless of your per minute rate limit, all partners will be limited to a maximum of 20 requests per second, aggregated across all requests for data and/or counts. |
Count Precision | The counts delivered through this endpoint reflect the number of Tweets that occurred and do not reflect any later compliance events (deletions, scrub geos). Some Tweets counted may not be available via data endpoint due to user compliance actions. |
Status | Text | Description |
---|---|---|
200 | OK | The request was successful. The JSON response will be similar to the following: |
400 | Bad Request | Generally, this response occurs due to the presence of invalid JSON in the request, or where the request failed to send any JSON payload. |
401 | Unauthorized | HTTP authentication failed due to invalid credentials. Log in to console.gnip.com with your credentials to ensure you are using them correctly with your request. |
404 | Not Found | The resource was not found at the URL to which the request was sent, likely because an incorrect URL was used. |
422 | Unprocessable Entity | This is returned due to invalid parameters in the query — e.g. invalid PowerTrack rules. |
429 | Unknown Code | Your app has exceeded the limit on connection requests. The corresponding JSON message will look similar to the following: |
500 | Internal Server Error | There was an error on the server side. Retry your request using an exponential backoff pattern. |
502 | Proxy Error | There was an error on server side. Retry your request using an exponential backoff pattern. |
503 | Service Unavailable | There was an error on server side. Retry your request using an exponential backoff pattern. |