InsightsTrack API
insightstrack-stream

InsightsTrack API

InsightsTrack supports two endpoints, one for receiving data, and one for editing rules that dictate what data is received through the primary connection. You may receive data for more than one Twitter account (or rule) in a single connection.

InsightsTrack is built for scale and flexibility, allowing you to configure the number of subscribed accounts on different streaming connections as you see fit.

Methods 

Method Description
GET /stream/insightstrack Open a connection to the InsightsTrack API
GET /rules/insightstrack Return a list of rules that are currently configured on a specific stream
POST /rules/insightstrack Add a new Twitter account for monitoring
POST _method=delete /rules/insightstrack Remove a Twitter account from being monitored

Authentication 

InsightsTrack requires the use of HTTPS and OAuth 2.0 Bearer Token with Bearer Token credentials.

For any request, you will need to set up a Twitter App and corresponding API Key using the App management console in the developer portal. This App ID will need to be added to an allowlist by us.

Authorization

In order to have access to the API, you must have your Twitter App ID added to an allowlist. To submit a new App to be used for this API, please reach out to your account manager. To find your Twitter App ID, log into apps.twitter.com with the App that you would like to use to query the API, and pull the integer out of the URL: (https://developer.twitter.com/en/apps/6218879).


GET /stream/insightstrack 

Open a connection to the InsightsTrack API.

Request Method HTTP GET
URL https://data-api.x.com/stream/insightstrack/accounts/{account-name}/publishers/twitter/{stream-label}.json
Content Format JSON
Keep-alives New-line keep-alives will be sent through the API every 3 seconds.
Parameters None. There are no supported parameters at this time.
Read Timeout Set a read timeout on your client, and ensure that it is set to a value beyond 30 seconds.

Example Request

curl -v - H "Authorization: Bearer $TOKEN" -H "content-type:application/json" -X GET "https://data-api.x.com/stream/insightstrack/accounts/{account-name}/publishers/twitter/{stream-label}.json"

Example Response (successfully connected)

200 OK

{"tweet_event":{"create":{"date_time":"Thu Apr 13 17:04:50 +0000 2017","target":{"id":852568271115108352,"id_str":"852568271115108352","user":{"id":3001969357,"id_str":"3001969357"}},"tweet":{"created_at":"Thu Apr 13 17:04:50 +0000 2017","id":852568271115108352,"id_str":"852568271115108352","text":"WOOHOOO THURSDAY!"....}}}}



{"tweet_event":{"create":{"date_time":"Thu Apr 13 17:10:27 +0000 2017","target":{"id":852569686839410689,"id_str":"852569686839410689","user":{"id":3001969357,"id_str":"3001969357"}},"tweet":{"created_at":"Thu Apr 13 17:10:27 +0000 2017","id":852569686839410689,"id_str":"852569686839410689","text":"RT @itsdougthepug: When someone tries to tell u that pizza isn't a food group https://t.co/OY2Q4MbCny"....}}}}

GET /rules/insightstrack 

Returns the current list of rules (from:userID rules) that are currently configured on a specific stream.

URL https://data-api.x.com/rules/insightstrack/accounts/{account-name}/publishers/twitter/{stream-label}.json
Request Method HTTP GET
Encoding UTF-8
Body Format JSON

Example Request

curl -v - H "Authorization: Bearer $TOKEN" -H "content-type:application/json" -X GET "https://data-api.x.com/rules/insightstrack/accounts/{account-name}/publishers/twitter/{stream-label}.json"

Example Response

{
    "rules": [{
            "value": "from:1234"
        },
        {
            "value": "from:5678"
        },
        {
            "value": "from:3001969357"
        }
    ],
    "sent": "2017-04-12T00:53:08.328Z"
}

Example Response

{"summary":{"created":1,"not_created":0},"details":[{"rule":{"value":"from:12345"},"created":true}],"sent":"Thu Apr 13 16:49:17 +0000 2017"}

Example Response

HTTP/1.1 422 Unprocessable Entity

{"summary":{"created":0,"not_created":1},"details":[{"rule":{"value":"from:ANYONE"},"created":false,"message":"Rule is not a Twitter User ID"}],"sent":"Thu Apr 13 18:29:32 +0000 2017"}

POST /rules/insightstrack 

Add a new Twitter account to be monitored for impression and engagement data. Rules are required to be Twitter User IDs that you would like to track in the form of “from” rules. We do not support other operators or rule formats at this time. The rules structure and JSON formats are consistent with PowerTrack. See examples in the body format section below.

URL https://data-api.x.com/rules/insightstrack/accounts/{account-name}/publishers/twitter/{stream-label}.json
Request Method HTTP POST
Encoding UTF-8
Size Limit 1,000 User IDs per request
Rate Limit 60 requests per minute, aggregated across all requests to /rules endpoint for the specific stream's API (POST and GET). Rule addition requests will be processed serially and will be rejected if you have more than one rule request happening at the same time.
Body Format JSON

POST Body Format

Your request should provide rule data in the following format:

{
  "rules":
  [
    {"value":"from:123456"},
    {"value":"from:9876543"}
    {"value":"from:3001969357"}
  ]
}

Example Request

curl -v - H "Authorization: Bearer $TOKEN" -H "content-type:application/json" -X POST "https://data-api.x.com/rules/insightstrack/accounts/{account-name}/publishers/twitter/{stream-name}.json" -d '{ "rules" : [ { "value" : "from:12345" } ] }'

Example Response

{"summary":{"created":1,"not_created":0},"details":[{"rule":{"value":"from:12345"},"created":true}],"sent":"Thu Apr 13 16:49:17 +0000 2017"}

Example Response

HTTP/1.1 422 Unprocessable Entity

{"summary":{"created":0,"not_created":1},"details":[{"rule":{"value":"from:ANYONE"},"created":false,"message":"Rule is not a Twitter User ID"}],"sent":"Thu Apr 13 18:29:32 +0000 2017"}

POST _method=delete /rules/insightstrack 

Remove a Twitter account from being monitored for impression and engagement data. This is done by sending a POST request to the rules endpoint and specifying a special parameter, ?_method=delete.

Request Specifications

URL https://data-api.x.com/rules/insightstrack/accounts/{account-name}/publishers/twitter/{stream-label}.json?_method=delete
Request Method HTTP POST
Encoding UTF-8
Parameter ?_method=delete
Body Format JSON

POST Body Format

{
  "rules":
  [
    {"value":"from:123456"},
    {"value":"from:789012"}
  ]
}

Example Request

curl -v - H "Authorization: Bearer $TOKEN" -H "content-type:application/json" -X POST "https://data-api.x.com/rules/insightstrack/accounts/{account-name}/publishers/twitter/{stream-name}.json?_method=delete" -d '{"rules":[{"value":"from:12345"},{"value":"from:987654"}]}'

Example Response

HTTP/1.1 200 OK

{"summary":{"deleted":2,"not_deleted":0},"details":[{"rule":{"value":"from:987654"},"deleted":true},{"rule":{"value":"from:12345"},"deleted":true}],"sent":"Thu Apr 13 18:10:09 +0000 2017"}

Responses

Status Text Description
200 OK The rule or rules were successfully deleted.
201 Created The rule or rules were successfully added.
400 Bad Request Poorly formatted JSON. Will include "Invalid JSON" message.
401 Unauthorized Invalid credentials or unauthorized to view data for this ID.
422 Unprocessable Entity IInvalid rule based on API restrictions. Requests fail or succeed as a batch. For these errors, each invalid rule and the reason is included in a JSON message in the response. Catch the associated exception to expose this message.
429 Rate Limit Exceeded the limit on requets to add or delete rules for this stream.
503 Service Unavailable Twitter server issue. Reconnect using an exponential backoff pattern. If no notice has been posted to api.twitterstat.us, contact support

Example Responses

HTTP/1.1 201 Created

{
  "summary": {
    "created": 2,
    "not_created": 0
  },
  "details": [
    {
      "rule": {
        "value": "from:123456"
      },
      "created": true
    },
    {
      "rule": {
        "value": "from:789012"
      },
      "created": true
    }
  ],
  "sent": "Mon Nov 14 22:09:10 +0000 2016"
}
HTTP/1.1 200 OK

{
  "deleted": 2,
  "details": [
    {
      "value": "from:123456"
    },
    {
      "value": "from:789012"
    }
  ],
  "sent": "Mon Nov 14 22:25:10 +0000 2016"
}
HTTP/1.1 400 Bad Request

{
    "error": {
        "message": "Invalid JSON. The body must be in the format {"rules":[{"value":"rule1"}, {"value":"rule2"}]}",
        "sent": "Mon Nov 14 22:25:10 +0000 2016"
    }
}
HTTP 1.1 422 Unprocessable Entity

{
  "summary": {
    "created": 0,
    "not_created": 1
  },
  "details": [
    {
      "rule": {
        "value": "from:99999999999999999999999999999"
      },
      "created": false,
      "message": "Rule is not a Twitter User ID"
    }
  ],
  "sent": "Mon Nov 14 22:36:05 +0000 2016"
}

Data Format

Connections to the InsightsTrack API should be maintained open as a streaming connection. Data will be returned through the connection corresponding to when specific events happened for Tweets of interest related to the Twitter @handle that you are monitoring. Additionally, full Tweet objects will be returned for Tweets that are created after you have initiated a connection to the API.


Summary objects

Delivery Details

The start time field represents the time at which the InsightsTrack system started aggregating metrics that will be included in the summary counts. The end time field represents the time at which the InsightsTrack system stopped aggregating metrics for this specific summary object. In other words, the metric counts included in each summary object represent what took place between the start and end times. Summary objects delivery data cumulatively, meaning they are running totals since we began tracking the Tweet.

Target

An array that includes the information for the Tweet ID and User to which the summary object pertains.

Metrics

An array that includes up to date counts for the impression and engagement events for a given Tweet. Counts represent the total number of actions.

{
    "summary_event": {
        "start_time": "Tue Jan 31 22:22:49 +0000 2017",
        "end_time": "Tue Jan 31 22:50:30 +0000 2017",
        "target": {
            "id": 112233445566778899,
            "id_str": "112233445566778899",
            "user": {
                "id": 123456789123456789,
                "id_str": "123456789123456789"
            }
        },
        "metrics": {
            "impressions": {
                "total": {
                    "count": "12"
                },
                "unique": {
                    "count": "5"
                }
            },
            "engagements": {
                "overall": {
                    "total": {
                        "count": "43"
                    },
                    "unique": {
                        "count": "4"
                    }
                },
                "metric_counts": {
                    "favorites": {
                        "total": {
                            "count": "1"
                        }
                    },
                    "media_clicks": {
                        "total": {
                            "count": "2"
                        }
                    },
                    "video_starts": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_viewed_100": {
                        "total": {
                            "count": "5"
                        }
                    },
                    "video_viewed_25": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_viewed_50": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_viewed_75": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_viewed_95": {
                        "total": {
                            "count": "6"
                        }
                    },
                    "video_views": {
                        "total": {
                            "count": "5"
                        }
                    }
                }
            }
        }
    }
}

User Event

When a user (@handle) revokes permissions for one of your connected accounts, we will send a user_event to notify you. Note that this also means we will delete this user as a rule and you will no longer receive any data associated with this user. If you believe that the user in question unrevokes or reads permissions for your App in the future, you should create a new rule to begin tracking data for them again.

An example user_event for this case looks like:

{
  "user_event": {
    "revoke": {
      "date_time": "2016-10-18T02:16:15.329Z",
      "target": {
        "app_id": 8798497
      },
      "source": {
        "user_id": 760886565136584704
      }
    }
  }
}

Tweet

For more information on the elements of a Tweet, please see Tweet objects.

{
  "tweet_event": {
    "create": {
      "date_time": "Wed Oct 10 20:19:24 +0000 2018",
      "target": {
        "id": "1050118621198921728",
        "id_str": "1050118621198921728",
        "user": {
          "id": "6253282",
          "id_str": "6253282"
        }
      },
      "tweet": {
        "created_at": "Wed Oct 10 20:19:24 +0000 2018",
        "id": "1050118621198921728",
        "id_str": "1050118621198921728",
        "text": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin t… https://t.co/MkGjXf9aXm",
        "source": "<a href="http://twitter.com" rel="nofollow">Twitter Web Client</a>",
        "truncated": false,
        "in_reply_to_status_id": null,
        "in_reply_to_status_id_str": null,
        "in_reply_to_user_id": null,
        "in_reply_to_user_id_str": null,
        "in_reply_to_screen_name": null,
        "user": {
          "id": 6253282,
          "id_str": "6253282",
          "name": "Twitter API",
          "screen_name": "TwitterAPI",
            "location": "San Francisco, CA",
            "profile_location": null,
            "description": "The Real Twitter API. Tweets about API changes, service issues and our Developer Platform. Don't get an answer? It's on my website.",
            "url": "https://t.co/8IkCzCDr19",
            "entities": {
                "url": {
                    "urls": [{
                        "url": "https://t.co/8IkCzCDr19",
                        "expanded_url": "https://developer.twitter.com",
                        "display_url": "developer.twitter.com",
                        "indices": [
                            0,
                            23
                        ]
                    }]
                },
                "description": {
                    "urls": []
                }
            },
            "protected": false,
            "followers_count": 6133636,
            "friends_count": 12,
            "listed_count": 12936,
            "created_at": "Wed May 23 06:01:13 +0000 2007",
            "favourites_count": 31,
            "utc_offset": null,
            "time_zone": null,
            "geo_enabled": null,
            "verified": true,
            "statuses_count": 3656,
            "lang": null,
            "contributors_enabled": null,
            "is_translator": null,
            "is_translation_enabled": null,
            "profile_background_color": null,
            "profile_background_image_url": null,
            "profile_background_image_url_https": null,
            "profile_background_tile": null,
            "profile_image_url": null,
            "profile_image_url_https": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg",
            "profile_banner_url": null,
            "profile_link_color": null,
            "profile_sidebar_border_color": null,
            "profile_sidebar_fill_color": null,
            "profile_text_color": null,
            "profile_use_background_image": null,
            "has_extended_profile": null,
            "default_profile": false,
            "default_profile_image": false,
            "following": null,
            "follow_request_sent": null,
            "notifications": null,
            "translator_type": null
        },
        "geo": null,
        "coordinates": null,
        "place": null,
        "contributors": null,
        "is_quote_status": false,
        "quote_count": 33,
        "reply_count": 30,
        "retweet_count": "0",
        "favorite_count": "0",
        "entities": {
          "hashtags": [],
          "urls": [
            {
              "url": "https://t.co/MkGjXf9aXm",
              "expanded_url": "https://twitter.com/i/web/status/1050118621198921728",
              "display_url": "twitter.com/i/web/status/1…",
              "indices": [
                117,
                140
              ]
            }
          ],
          "user_mentions": [],
          "symbols": []
        },
        "favorited": false,
        "retweeted": false,
        "filter_level": "low",
        "lang": "en"
        "timestamp_ms": "1893456061000"
      }
    }
  }
}