Graph API Version

/<privacy-group>/threat_updates

This call is not currently enabled for all PrivacyGroups. A 500 error will be returned if this call is used with a not yet enabled PrivacyGroup. If ou would like to enable this call for your privacy group please contact the ThreatExchange team.

This API call enables querying for Indicators and related subjective data stored in ThreatExchange that is within a specified privacy group. With this call you can query for signals that have been updated (created, modified, or deleted) in a specific time window and further filter to only query for specific types of indicators.

This call should be the primary method for staying in sync with a ThreatExchange dataset. To complete the inital download you should use this call with no start or stop time parameters. Then, at some regular cadence, you should download all updates and deletes since the last time you polled. The ideal cadence of updates should be in line with your tolerance for latency data.

Instead of building an implementation from scratch, you can start with our Python opensource library which can also be used as a reference implementation.

After a descriptor is deleted or removed from a privacy group, a record of that deletion will be visible from this callsite as an update for 90 days following the deletion/removal. After 90 days, this call will no longer return the deletion record. Becuase of this, you must poll updates using this call at least once every 90 days to be notified of deletions however, we recomend polling much more often to stay up to date with the data.

This call may reveal indicators that have been deleted from the privacy group queried. When you recieve notice of a deletion you should delete all internal references to that data. See Terms and Conditions for more.

Parameters

The following query parameters are available (bold parameters are required):

  • access_token - The key for authenticating to the API.
  • types - The types of indicators to search for.
  • start_time - Search for indicators that last updated on or after this timestamp.
  • stop_time - Search for indicators that last updated before this timestamp.
  • limit - Defines the maximum size of a page of results
  • fields - A list of fields to return in the response, if not specified all fields are returned.
    • indicator - The value of the indicator.
    • type - The type of indicator this is.
    • creation_time - The timestamp of when the indicator was created.
    • last_updated - The timestamp of when the indicator was last updated.
    • tags - A list of tags associated with this indicator.
    • descriptors - A list of subjective opinions for this indicator.
    • status - The worst subjective opinion of ThreatStatus for this indicator.
    • applications_with_opinions - A list of applications with subjective opinions on this indicator.
    • should_delete - Whether this indicator should be deleted or not.

Example query for all indicators that last updated between December 2019 (1575187200) to March 2020 (1583049600) for privacy group 123456789012345, and are of type HASH_PDQ or HASH_MD5:

https://graph.facebook.com/v9.0/123456789012345/threat_updates/?access_token=555|aSdF123GhK&start_time=1575187200&stop_time=1583049600&types=HASH_MD5,HASH_PDQ&fields=id,indicator,type,creation_time,last_updated,should_delete,tags,status,applications_with_opinions

Data Returned:

{
    "data": [
        {
            'id': '123456',
            'indicator': 'a_hash_that_was_created_or_updated',
            'type': 'HASH_PDQ',
            'creation_time': 1581977111,
            'last_updated': 1582372222,
            'should_delete': False,
            'tags': ['tag1', 'another_tag'],
            'status': 'MALICIOUS',
            'applications_with_opinions': ['1234567890']
        },
        {
            'id': '123457',
            'indicator': 'a_hash_that_should_be_deleted',
            'type': 'HASH_PDQ',
            'creation_time': 1581977111,
            'last_updated': 1582372222,
            'should_delete': True,
            'tags': ['tag1', 'another_tag'],
            'status': 'MALICIOUS',
            'applications_with_opinions': ['1234567890']
        },
        ...
    ]
    "paging": {
        "cursors": {
            "before": "MjVFR",
            "after": "MjQZD"
        }
    "next": "https://graph.facebook.com/v9.0/123456789012345/threat_updates/?access_token=555|aSdF123GhK&amp;start_time=1575187200&amp;stop_time=1583049600&amp;types=HASH_MD5,HASH_PDQ&amp;fields=id,indicator,type,creation_time,last_updated,should_delete,tags,status,applications_with_opinions&amp;after=MjQZD"
    }
}