PowerTrack API

This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the [“Edit Posts” fundamentals page](/x-api/enterprise-…

This endpoint has been updated to include Post edit metadata. Learn more about these metadata on the “Edit Posts” fundamentals page. 

Overview

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

You can view all of the X API filtered stream offerings HERE.

The PowerTrack API provides customers with the ability to filter the full X firehose, and only receive the data that they or their customers are interested in. This is accomplished by applying the PowerTrack filtering language - see Rules and filtering - to match Posts based on a wide variety of attributes, including user attributes, geo-location, language, and many others. Using PowerTrack rules to filter Post ensures that customers receive all of the data, and only the data they need for your app.

Core components

The PowerTrack API consists of two endpoints:

Rules endpoint

A separate endpoint managed independently by your application, the rules endpoint supports GET, POST, POST _method=delete and rule validation methods with basic authentication for managing your ruleset. It can support thousands of rules that allow you to filter the realtime stream of data for the topics and conversations that you care about. The rules endpoint can be accessed, managed, and will persist regardless of your connection status to the stream - you can also update (add/remove) rules while connected to the stream and the changes will take effect almost immediately.

Stream endpoint

Connecting to the streaming endpoint consists of a simple GET request using basic authentication. Once a connection is established, data is delivered in JSON format (see sample payload below) through a persistent HTTP Streaming connection. You will only receive data matching your rules while connected to the stream.

Rule tags

A single PowerTrack stream can support thousands of rules, so being able to discern which rule(s) matched a given Post becomes important. This is easily solved by using rule tags. Upon rule creation, you can assign a tag value which will be returned in the matching_rules object (see here) of the response payload.

Rule tags can represent an end customer use case, a topic or conversation, or another helpful identifier that you can use to route incoming Posts accordingly.

If, in addition to realtime data, your product also requires instant access to recent data, we recommend using our Search API.

Available operators

The PowerTrack API currently supports the following operators:

• keyword
• emoji
• “exact phrase match”
• “keyword1 keyword2”~N
• contains:
• from:
• to:
• url:
• url_title:
• url_description:
• url_contains:
• has:links
• sample:
• point_radius:[lon lat radius]
• bounding_box:[west_long south_lat east_long north_lat]
• @
• $
• bio:
• bio_name:
• retweets_of:
• lang:
• bio_location:
• statuses_count:
• followers_count:
• friends_count:
• listed_count:
• is:verified
• source:
• place:
• place_country:
• has:geo
• has:mentions
• has:hashtags
• has:images
• has:videos
• has:media
• has:symbols
• is:retweet
• is:reply
• is:quote
• retweets_of_status_id:
• in_reply_to_status_id:
• has:profile_geo
• profile_point_radius:[long lat radius]
• profile_bounding_box:[west_long south_lat east_long north_lat]
• profile_country:
• profile_region:
• profile_locality:
• profile_subregion:

For more details, please see the Getting started with enterprise rules guide.

Sample payload

Below is a sample payload from the PowerTrack API in Native Enriched format:

{
  "created_at": "Wed Oct 10 20:19:24 +0000 2018",
  "id": 1050118621198921700,
  "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://x.com\" rel=\"nofollow\">X Web Client</a>",
  "truncated": true,
  "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": "X API",
    "screen_name": "API",
    "location": "San Francisco, CA",
    "url": "https://developer.x.com",
    "description": "The Real X API. Tweets about API changes, service issues and our Developer Platform. Don't get an answer? It's on my website.",
    "translator_type": "null",
    "derived": {
      "locations": [
        {
          "country": "United States",
          "country_code": "US",
          "locality": "San Francisco",
          "region": "California",
          "sub_region": "San Francisco County",
          "full_name": "San Francisco, California, United States",
          "geo": {
            "coordinates": [
              -122.41942,
              37.77493
            ],
            "type": "point"
          }
        }
      ]
    },
    "protected": false,
    "verified": true,
    "followers_count": 6172196,
    "friends_count": 12,
    "listed_count": 13003,
    "favourites_count": 31,
    "statuses_count": 3650,
    "created_at": "Wed May 23 06:01:13 +0000 2007",
    "utc_offset": null,
    "time_zone": null,
    "geo_enabled": false,
    "lang": "en",
    "contributors_enabled": false,
    "is_translator": null,
    "profile_background_color": "null",
    "profile_background_image_url": "null",
    "profile_background_image_url_https": "null",
    "profile_background_tile": null,
    "profile_link_color": "null",
    "profile_sidebar_border_color": "null",
    "profile_sidebar_fill_color": "null",
    "profile_text_color": "null",
    "profile_use_background_image": null,
    "profile_image_url": "null",
    "profile_image_url_https": "https://pbs.twimg.com/profile_images/942858479592554497/BbazLO9L_normal.jpg",
    "profile_banner_url": "https://pbs.twimg.com/profile_banners/6253282/1497491515",
    "default_profile": false,
    "default_profile_image": false,
    "following": null,
    "follow_request_sent": null,
    "notifications": null
  },
  "geo": null,
  "coordinates": null,
  "place": null,
  "contributors": null,
  "is_quote_status": false,
  "extended_tweet": {
    "full_text": "To make room for more expression, we will now count all emojis as equal—including those with gender‍‍‍ ‍‍and skin tone modifiers 👍🏻👍🏽👍🏿. This is now reflected in Twitter-Text, our Open Source library. \n\nUsing Twitter-Text? See the forum post for detail: https://t.co/Nx1XZmRCXA",
    "display_text_range": [
      0,
      277
    ],
    "entities": {
      "hashtags": [],
      "urls": [
        {
          "url": "https://t.co/Nx1XZmRCXA",
          "expanded_url": "https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607",
          "display_url": "devcommunity.com/t/new-update-t…",
          "unwound": {
            "url": "https://devcommunity.x.com/t/new-update-to-the-twitter-text-library-emoji-character-count/114607",
            "status": 200,
            "title": "New update to the Twitter-Text library: Emoji character count",
            "description": "Over the years, we have made several updates to the way that people can communicate on X. One of the more notable changes made last year was to increase the number of characters per Tweet from 140 to 280 characters. Today, we continue to expand people’s ability to express themselves by announcing a change to the way that we count emojis. Due to the differences in the way written text and emojis are encoded, many emojis (including emojis where you can apply gender and skin tone) have count..."
          },
          "indices": [
            254,
            277
          ]
        }
      ],
      "user_mentions": [],
      "symbols": []
    }
  },
  "quote_count": 0,
  "reply_count": 0,
  "retweet_count": 0,
  "favorite_count": 0,
  "entities": {
    "hashtags": [],
    "urls": [
      {
        "url": "https://t.co/MkGjXf9aXm",
        "expanded_url": "https://x.com/i/web/status/1050118621198921728",
        "display_url": "x.com/i/web/status/1…",
        "indices": [
          117,
          140
        ]
      }
    ],
    "user_mentions": [],
    "symbols": []
  },
  "favorited": false,
  "retweeted": false,
  "possibly_sensitive": false,
  "filter_level": "low",
  "lang": "en",
  "timestamp_ms": "1539202764211",
  "matching_rules": [
    {
      "tag": null,
      "id": 1128017341835464700,
      "id_str": "1128017341835464704"
    }
  ]
}
}

See code examples: 

• See simple scripts in several languages to help get started

• See an example Java client libraries: Hosebird Client adapted for enterprise streams, Gnip4J

• See an example Python client library

Guides

Integrating with PowerTrack

To integrate PowerTrack into your product, you will need to build an application that can do the following:

1. Establish a streaming connection to the PowerTrack stream API.
2. Asynchronously send POST requests to the PowerTrack rules API to add and delete rules from the stream.
3. Handle low data volumes – Maintain the streaming connection, and ensure buffers are flushed regularly.
4. Handle high data volumes – de-couple stream ingestion from additional processing using asynchronous processes.
5. Reconnect to the stream automatically when disconnected for any reason.

For details on the types of requests needed for tasks 1 and 2, and important considerations in implementing them, see the API reference.

Rules & Filtering

PowerTrack enhances the ability to filter X’s full firehose, and only receive the data that they or their customers are interested in. This is accomplished by applying PowerTrack filtering language to match Posts based on a wide variety of attributes, including user attributes, geo-location, language, and many others. Using PowerTrack rules to filter a data source ensures that customers receive all of the data, and only the data they need for your app.

As described, customers add filtering rules to the PowerTrack stream to determine which activities will be sent through the connection. The PowerTrack stream can support thousands of these individual rules, and deliver the combined set of matching activities through the single stream connection.

The set of PowerTrack rules used to filter a customer’s stream is highly flexible. If a customer needs to add a new filtering rule to capture a different type of content, or remove an existing rule, their app can send a request to the PowerTrack API to make it happen. When that request is sent, the filtering rules are automatically modified and the changes simply take effect in the data stream with no need to reconnect. This allows customers to provide data for many customers at scale, while supporting distinct filtering requirements for each of those customers.

[See Complete List of Operators »](/x-api/enterprise-gnip-2.0/powertrack-api#available-o