Enterprise
This is an enterprise API available within our managed access levels only. To use this API, you must first set up an account with our enterprise sales team. Learn more
The Engagement API provides access to Post impression and engagement metrics. While most metrics and endpoints require you to authenticate using OAuth 1.0a User Context, you can access public Favorite, Retweet, Reply, and Video Views metrics using OAuth 2.0 Bearer Token and the /totals endpoint.
Note: You may observe differences between reported data on some of the X web dashboards, and the data reported in the Engagement API. These differences occur because the web dashboards typically only show engagements and/or impressions that occurred within the selected time range. For example, a web dashboard may show engagement on Posts within the span of a calendar month, while the Engagement API may show engagements that fall beyond the span of that month, but within the time range requested. The Engagement API should be seen as the valid source, in these cases.
Metric | Endpoint Availability | User Context Required | Description |
---|---|---|---|
impressions | All | Yes | A count of how many times the Post has been viewed. This metric is only available for Posts that have been posted within the past 90 days. |
engagements | All | Yes | A count of the number of times a user has interacted with the Post. This metric is only available for Posts that have been posted within the past 90 days. |
favorites | All | Yes - /28hrs & /Historical No - /totals | A count of how many times the Post has been favorited. |
retweets | All | Yes - /28hrs & /Historical No - /totals | A count of how many times the Post has been Retweeted. |
quote_tweets | /totals | No - /totals | A count of times a Post has been Retweeted with a comment (also known as Quote). |
replies | All | Yes - /28hrs & /Historical No - /totals | A count of how many times the Post has been replied to. |
video_views | All | Yes - /28hrs & /Historical No - /totals | A count of how many times a video in the given Post has been 50% visible for at least two seconds. Video views are only available for Posts that are 1800 days old or less. If you try to request video views for any Posts older than 1800 days, you will receive the following object within your response, along with a separate object that contains any other metrics that you requested: “unsupported_for_video_views_tweet_ids”: [“TWEET_ID”] Please note: You may see a discrepancy between the video views metric displayed in the X owned and operated platforms (mobile app and website) and the number that you receive via the /28hr and /historical endpoints. * The video views displayed in the X user interface and with the /totals endpoint will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric displayed in the UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Posts. This metric does not include video views on gifs. * The video views provided by the /28hr and /historical endpoints will just include those views generated by the specific Post for which you are pulling metrics. This metric does not include video views on gifs. |
media_views | /28hr /historical | Yes | A count of all views (autoplay and click) of your media counted across videos, gifs, and images. |
media_engagements (formerly Media Clicks) | /28hr /historical | Yes | A count of how many times media such as an image or video in the Post has been clicked. |
url_clicks | /28hr /historical | Yes | A count of how many times a URL in the Post has been clicked. |
hashtag_clicks | /28hr /historical | Yes | A count of how many times a hashtag in the Post has been clicked. |
detail_expands | /28hr /historical | Yes | A count of how many times the Post has been clicked to see more details. |
permalink_clicks | /28hr /historical | Yes | A count of how many times the permalink to the Post (the individual web page dedicated to this Post) has been clicked. |
app_install_attempts | /28hr /historical | Yes | A count of how many times an App Install event has occurred from the Post |
app_opens | /28hr /historical | Yes | A count of how many times an App Open event has occurred from the Post. |
email_tweet | /28hr /historical | Yes | A count of how many times the Post has been shared via email. |
user_follows | /28hr /historical | Yes | A count of how many times the User (Post author) has been followed from this Post. |
user_profile_clicks | /28hr /historical | Yes | A count of how many times the User (Post author) has had their profile clicked from this Post. |
/28hr
and /historical
can provide time-series metrics, and thus support:
1/ Today we’re sharing our vision for the future of the X API platform— Twitter Dev (@TwitterDev) April 6, 2017
Don’t miss the Posts about your Post. Now on iOS, you can see Retweets with comments all in one place. pic.x.com/oanjZfzC6y — X (@X) May 12, 2020The first step is constructing the API request in JSON, consisting of these two Post IDs placed in an array, an array of engagement types of interest, and a custom-named “groupings” JSON object that indicates how we want the metrics arranged in the response. Here is what our request looks like:
Please note: X needs to enable access to the Engagement API for your developer App before you can start using the API. To this end, make sure to share the App ID that you intend to use for authentication purposes with your account manager or technical support team.There are two authentication methods available with the Engagement API: OAuth 1.0a and OAuth 2.0 Bearer Token. OAuth 2.0 Bearer Token (also referred to as “application-only”) allows you to access publicly available engagement metrics. This authentication method can be used to get total counts for Favorites (aka Likes), Retweets, Quote Tweets, Replies, and video views for any publicly available Posts when making requests to the /totals endpoint. OAuth 1.0a (also referred to as “user context”) allows you to make requests on behalf of a user and access private engagement metrics that belong to the user in question. This authentication method is required for:
403 Forbidden
error.
The Engagement API will not allow you to fetch engagement data for protected Posts, even if you are authenticating on behalf of the user who owns these Posts. Attempting to do so will return a 400 Bad Request
error, with the message "Tweet ID(s) are unavailable"
.
If you are sending a request on behalf of your own X account (in other words, the account that owns the developer App), you can generate the required Access Tokens directly from within the developer portal, under the “Keys and tokens” tab for the developer App.
If you are making a request on behalf of any other user, you will need to use the 3-legged OAuth flow to obtain the required Access Tokens. The following documentation contains more information on how to do this: OAuth 1.0a: how to obtain a user’s access tokens.
For additional examples, including how to authenticate using OAuth 1.0a, check outXDevelopers sample Python code for the Engagement API.
Metric | Change |
engagements | We’ve updated the metrics that roll into overall engagements to match consistency with the Post analytics dashboard. Engagements measures “times people interacted with this Post”. For Posts that include media like a video or a GIF, the engagements metric will no longer include media views. Media views can now be accessed in a new metric, media_views. |
media_clicks* | This metric has been replaced by a new metric called “media_engagements”. |
video_views | As of July 6th, 2018, this metric is now available for ‘unowned’ Posts via the /totals endpoint. This means that you can access the video views for all Posts by using app-only authentication. You can only request video views that are younger than 1800 days old. If you try to request video views for a Post older than 1800 days, you will receive the following: “unsupported_for_video_views_tweet_ids”: [“TWEET_ID”] Please note that it will differ from media_views in that video_views relies on the MRC standard of 50% of the video in view for at least two seconds. Also, note that you may see a discrepancy between the video views metric displayed in the X owned and operated platforms (mobile app and website) and the number that you receive via the /28hr and /historical endpoints. * The video views displayed in the X user interface and that delivers using the /totals endpoint will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric displayed in the UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Posts. * The video views provided by the /28hr and /historical endpoints will just include those views generated by the specific Post for which you are pulling metrics. |
media_views | This includes all views (autoplay and click) of your media counted across videos, vines, gifs, and images. Please note that Posts with images do not show a media_views metric in the analytics dashboard but will be returned in the Engagement API. |
media_engagements* | This includes the number of clicks on your media across videos, vines, gifs, and images. This metric is replacing media_clicks. |
quote_tweets | As of July 7th, 2020, this metric is now available for ‘unowned’ Posts via the /totals endpoint. This means that you can access the Quote Post count for all Posts by using app-only authentication. |
/28hr
and /historical
can provide time-series metrics, and thus support:
group_by
values. Groupings that contain four group_by
values will only be supported in one of the following two formats:
"Grand Totals"
attribute which contains grand totals by metrics type:
"Tweets_MetricType_TimeSeries"
attribute which contains the metrics broken down by Post ID, then metric type, and the corresponding hourly time-series:
Enterprise
How can I access the Engagement API?
How is my usage tracked by '@handle'?
Can I check my @handle usage for Engagement API?
engagements
metadata field returned in the payload is not equal to the sum of all the various engagement metric totals. Why is this the case?This is to be expected. The engagements
metadata field may not always correlate with the sum of all individual engagement metrics returned by the API. This is because the engagements
metadata field may include additional engagements that do not have specific metrics broken out in the payload. Said another way, adding all of the various engagement metric totals together may not equal the value you are seeing in the engagements
metric field that is returned to you in the payload.You can think of the engagements
metadata field as any click or interaction made on the Post.
The url_clicks
field in the payload response is returning a number, when in fact the Post does not have a URL. How is this possible?This may be because a Post that contains something like a hashtag (that creates a link to another page) will count as a URL click if it is clicked on by a user.
Why can I not receive engagement data for a specific Post?
How can I handle rate limiting with the Engagement API?
x-per-minute-limit
and x-per-minute-remaining
information returned by the response header when you make a request to the Engagement API to monitor your consumption.x-per-minute-limit
tells you what your allowance is and x-per-minute-remaining
tells you how many calls you have left.I am having problems authenticating
I have passed the correct consumer key and secret, as well as access token and access token secret, but the following error is being returned. What can I do?
I have a question that hasn't yet been answered
Method | Description |
---|---|
POST /insights/engagement/totals | Retrieve total impressions and engagements for a collection of Tweets. |
POST /insights/engagement/historical | Retrieve impressions and engagements for a collection of Tweets for a period up to 4 weeks in duration, back to September 1, 2014. |
POST /insights/engagement/28hr | Retrieve impressions and engagements for a collection of Tweets for the past 28 hours. |
Request Method | HTTP POST |
URL | https://data-api.x.com/insights/engagement/totals |
Content Type | application/json |
Compression | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request. The header should look like the following: Accept-Encoding: gzip |
POST Format | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a tweets , engagements , and groupings object. Each request can have a maximum of 250 Tweet IDs. An example POST body looks like: { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “favorites”, “quote_tweets” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } } |
Tweet IDs | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to request data for Tweets that were created by the authenticating @handle. Up to 250 Tweets may be included per request, and Tweet IDs must be represented as strings. |
Engagement Types | An array that includes the types of engagement metrics to be queried. The Totals endpoint supports only the following engagement types: impressions , engagements , favorites , retweets , quote_tweets , replies , video_views . The /totals endpoint supports the ability to retrieve impressions and engagements for Tweets created within the last 90 days, and favorites , retweets , quote_tweets , replies , and video_views for any Tweet. |
Groupings | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request. For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application. Once you have defined a grouping name, you can choose to group tweet.id and/or engagement.type . Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID and metric type looks like: “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } |
POST Size Limit | Requests can be made for a maximum of 250 Tweet IDs at a time. |
Response Format | JSON. The header of your request should specify JSON format for the response. |
Rate Limit | You will be rate limited by minute, as specified in your contract according to your level of access. |
Example Request (public metrics) | curl —request POST —url https://data-api.x.com/insights/engagement/totals —header ‘accept-encoding: gzip’ —header ‘authorization: Bearer ’ —header ‘content-type: application/json’ —data ’{ “tweet_ids”: [ “1070059276213702656”,“1021817816134156288”,“1067094924124872705” ], “engagement_types”: [ “favorites”,“retweets”,“replies”,“quote_tweets”,“video_views” ], “groupings”: { “perTweetMetricsUnowned”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } } —verbose —compressed |
Example Request | curl —request POST —url https://data-api.x.com/insights/engagement/totals —header ‘accept-encoding: gzip’ —header ‘authorization: OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ —header ‘content-type: application/json’ —data ’{ “tweet_ids”: [ “1060976163948904448”,“1045709644067471360” ], “engagement_types”: [ “favorites”,“replies”,“retweets”,“video_views”,“impressions”,“engagements” ], “groupings”: { “perTweetMetricsOwned”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } }’ —verbose —compressed |
Example Response (public metrics) | { “perTweetMetricsUnowned”: { “1021817816134156288”: { “favorites”: “530”, “quote_tweets”: “79”, “replies”: “147”, “retweets”: “323”, “video_views”: “0” }, “1067094924124872705”: { “favorites”: “1360”, “quote_tweets”: “29”, “replies”: “56”, “retweets”: “178”, “video_views”: “5754512” }, “1070059276213702656”: { “favorites”: “69”, “quote_tweets”: “5”, “replies”: “7”, “retweets”: “26”, “video_views”: “0” } } } |
Example Response | { “perTweetMetricsOwned”: { “1045709644067471360”: { “engagements”: “2”, “favorites”: “0”, “impressions”: “47”, “replies”: “0”, “retweets”: “8”, “quote_tweets”: “5”, “video_views”: “0” }, “1060976163948904448”: { “engagements”: “4”, “favorites”: “0”, “impressions”: “148”, “replies”: “1”, “retweets”: “9”, “quote_tweets”: “2”, “video_views”: “0” } } } |
Unavailable Tweet IDs | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called unavailable_tweet_ids . For example: { “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:00:00Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: “26”, “quote_tweets”: “2” } } } |
Request Method | HTTP POST |
URL | https://data-api.x.com/insights/engagement/28hr |
Content Type | application/json |
Compression | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request. The header should look like the following: Accept-Encoding: gzip |
POST Format | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a tweets , engagements , and groupings object. Each request can have a maximum of 25 Tweet IDs. An example POST body looks like: { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.hour” ] } } } |
Tweet IDs | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to requests data for Tweets that were created by the authenticating @handle. The 28 hour endpoint supports up to a maximum of 25 Tweets per request, and Tweet IDs must be represented as strings. |
Engagement Types | An array the types of engagement metrics to be queried. For the 28 hour endpoint, impressions , engagements , and all individual engagement types are supported metrics. For the full list of supported engagement metrics see Engagement Data. |
Groupings | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request. For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application. Once you have defined a grouping name, you can choose to group by one or more of the following values: tweet.id engagement.type engagement.day engagement.hour Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID, metric type, and looks like: “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day” ] } } Groupings that have 4 group_by items are only valid if they use one of the following two orders. Requests that have 4 group_by items in a single grouping that are not one of the following will return an error. Additionally, only one grouping with 4 group_by items will be allowed per request. “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] “group_by”: [ “engagement.type”, “tweet.id”, “engagement.day”, “engagement.hour” ] |
POST Size Limit | Requests can be made for a maximum of 25 Tweet IDs at a time. |
Response Format | JSON. The header of your request should specify JSON format for the response. |
Rate Limit | You will be rate limited by minute, as specified in your contract according to your level of access. |
Example Request | curl -X POST “https://data-api.x.com/insights/engagement/28hr” -H ‘Accept-Encoding: gzip’ -H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ -d ’{ “tweet_ids”: [ “123456789” ], “engagement_types”: [ “impressions”, “engagements” ], “groupings”: { “hourly-time-series”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] } } }‘ |
Example Response | { “start”: “2015-09-14T17:00:00Z”, “end”: “2015-09-15T22:00:00Z”, “hourly-time-series”: { “123456789”: { “impressions”: { “2015-09-14”: { “17”: “551”, “18”: “412”, “19”: “371”, “20”: “280”, “21”: “100”, “22”: “19”, “23”: “6” }, “2015-09-15”: { “00”: “5”, “01”: “2”, “02”: “7”, “03”: “3”, “04”: “1”, “05”: “0”, “06”: “0”, “07”: “0”, “08”: “0”, “09”: “0”, “10”: “0”, “11”: “0”, “12”: “0”, “13”: “0”, “14”: “0”, “15”: “0”, “16”: “0”, “17”: “0”, “18”: “0”, “19”: “0”, “20”: “0”, “21”: “0” } }, “engagements”: { “2015-09-14”: { “17”: “0”, “18”: “0”, “19”: “0”, “20”: “0”, “21”: “0”, “22”: “0”, “23”: “0” }, “2015-09-15”: { “00”: “0”, “01”: “0”, “02”: “0”, “03”: “0”, “04”: “0”, “05”: “0”, “06”: “0”, “07”: “0”, “08”: “0”, “09”: “0”, “10”: “0”, “11”: “0”, “12”: “0”, “13”: “0”, “14”: “0”, “15”: “0”, “16”: “0”, “17”: “0”, “18”: “0”, “19”: “0”, “20”: “0”, “21”: “0” } } } } } |
Unavailable Tweet IDs | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called unavailable_tweet_ids . For example: { “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:00:00Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: 26 } } } |
Request Method | HTTP POST |
URL | https://data-api.x.com/insights/engagement/historical |
Content Type | application/json |
Compression | Gzip. To make a request using Gzip compression, send an Accept-Encoding header in the connection request. The header should look like the following: Accept-Encoding: gzip |
POST Format | Requests can be sent as a POST request where the body is a JSON object containing a collection of Tweet IDs and a desired grouping. The POST is formatted as an array with a tweets , engagements , and groupings object. Each request can have a maximum of 25 Tweet IDs. Each request can be specified with a custom Start and End date up to four weeks in duration. { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.hour” ] } } } |
Start and End Date | A custom start and end date can be specified with the start and end values as part of the request. You must specify a start and end date that are not longer than 4 weeks in duration. The oldest possible start date at this time is September 1, 2014. End dates in the future are not supported. If no Start and End date are supplied, the API will default to the immediately previous 4 weeks. The lowest granularity that data can be returned from the Engagement API is by hour. For any requests made with Start or End values that do not fall directly on an hourly boundary, requests will default to the nearest inclusive hour. For instance, a request with “start”:“2015-07-01T12:24:00Z” and “end”:“2015-07-10T08:37:00Z” will default to “start”:“2015-07-01T12:00:00Z”,“end”:“2015-07-10T09:00:00Z”. |
Tweet IDs | An array that includes the Tweet IDs for the Tweets to be queried for engagement data. Please note that you are only able to requests data for Tweets that were created by the authenticating @handle. The 4 week historical endpoint supports up to a maximum of 25 Tweets per request, and Tweet IDs must be represented as strings. |
Engagement Types | n array that includes the types of engagement metrics to be queried. For the 4 week historical endpoint, impressions , engagements , and all individual engagement types are supported metrics. For the full list of supported engagement metrics see Engagement Data. **Note:**Currently there are three metrics that will display as zero for queries made before September 15, 2015: favorites , replies , and retweets . |
Groupings | Results from the Engagement API can be returned in different groups to best fit your needs. You can include a maximum of 3 groupings per request. For each grouping, you may define a custom grouping name to make it easier to refer to this grouping type in your application. Once you have defined a grouping name, you can choose to group by one or more of the following values: tweet.id engagement.type engagement.day engagement.hour Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. An example grouping that will show metrics separated by Tweet ID, metric type, and looks like: “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day” ] } } Groupings that have 4 group_by items are only valid if they use one of the following two orders. Requests that have 4 group_by items in a single grouping that are not one of the following will return an error. Additionally, only one grouping with 4 group_by items will be allowed per request. “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] “group_by”: [ “engagement.type”, “tweet.id”, “engagement.day”, “engagement.hour” ] |
POST Size Limit | Requests can be made for a maximum of 25 Tweet IDs at a time. |
Response Format | JSON. The header of your request should specify JSON format for the response. |
Rate Limit | You will be rate limited by minute, as specified in your contract according to your level of access. |
Example Request | curl -XPOST “https://data-api.x.com/insights/engagement/historical” -H ‘Accept-Encoding: gzip’ -H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ -d ’{ “start”: “2015-08-01”, “end”: “2015-08-15”, “tweet_ids”: [ “123456789”, “223456789”, “323456789” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “types-by-tweet-id”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } }‘ |
Example Response | { “start”: “2015-08-01T00:00:00Z”, “end”: “2015-08-15T00:00:00Z”, “types-by-tweet-id”: { “123456789”: { “impressions”: “0”, “engagements”: “0”, “url_clicks”: “0”, “detail_expands”: “0” }, “223456789”: { “impressions”: “788”, “engagements”: “134”, “url_clicks”: “30”, “detail_expands”: “1323” }, “323456789”: { “impressions”: “4”, “engagements”: “0”, “url_clicks”: “2”, “detail_expands”: “0” } } } |
Unavailable Tweet IDs | For queries that include Tweet IDs that have been made unavailable (e.g., have been deleted), appropriate data will be returned for all available Tweet IDs, and unavailable Tweet IDs will be referenced in an array called unavailable_tweet_ids . For example:{ “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:27:50Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: 26 } } } |
Status | Text | Description |
---|---|---|
200 | OK | The request was successful. |
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. Check your OAuth keys and tokens. |
404 | Not Found | The resource was not found at the URL to which the request was sent, likely because an incorrect URL was used. |
429 | Too Many Requests | Your app has exceeded the limit on API requests. |
500 | Internal Server Error | There was an error on Gnip’s side. Retry your request using an exponential backoff pattern. |
502 | Proxy Error | There was an error on Gnip’s side. Retry your request using an exponential backoff pattern. |
503 | Service Unavailable | There was an error on Gnip’s side. Retry your request using an exponential backoff pattern. |
Error Message | Description |
---|---|
"errors":["Your account could not be authenticated. Reason: Access token not found"] | An error in the authentication component of the request. The “Reason” should provide information that is helpful to troubleshoot the error. In cases where you are not able to resolve, please send the full error, including the “Reason”, to our support team. |
"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"] | The Tweet ID or IDs you have requested are no longer available, usually indicating that they have been deleted or are no longer publicly available for another reason. |
"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*] | The Tweet ID or IDs you have requested specific to the /totals endpoint are not 90 days or newer and are thus not available for returning the impressions or engagements metrics. |
"errors":["Forbidden to access tweets: *TWEET_IDS*"] | The Tweet ID or IDs you have requested are not available based on the authentication token you are using to retrieve data on behalf of a third party. |