Alerts API Returns More Detections Than I'd Expect, Which timestamp is Which?

[patricktsullivan]

I am pulling detections using the following, hoping to get up to 10,000 detections, 100 at a time, from the last hour.

duration = 0.0417 # Duration in days to search for alerts (0.0417 = 1 hour)
start_time = time.strftime('%Y-%m-%dT%H:%M:%S', time.localtime(time.time() - (duration * 24 * 3600)))+'Z'
# Default = 100, MAX = 10000
limit_composite_ids = 100
query_string = ""
filter_string = f"context_timestamp:>='{start_time}'"

response = alerts_client.query_alerts_v2(offset=0,
                                  limit=limit_composite_ids,
                                  include_hidden=True,
                                  sort="timestamp|asc",
                                  filter=filter_string,
                                  q=query_string
                                  )

Looking in the console right now, I have about 200 detections showing from the last hour, but when I run the above, I'm getting over 1,000.

There are so many different timestamp values in the results, and I'm not sure which one represents what.
The strangest part, to me, though, is that for the first detection I get back from the above, I have
"context_timestamp": "2025-06-13T14:56:34.669Z"
and the final gives
"context_timestamp": "2025-06-13T19:54:59.894Z"

If my start_time is an hour ago, and I'm trying to filter on context_timestamp>:now()-1hour, how do I get two context_timestamp values about 5 hours apart?

[tsullivan06]

Thanks for using FalconPy. The following is some information related to the question(s) and code you posted.

Getting more responses within a larger time window than expected:

The most likely reason that you’re getting two context_timestamp values beyond the 1 hour look back has to do with the time calculations. The ‘start_time’ value is converting the local time minus one hour and using that for the baseline of the filter. The issue with that is ‘context_timestamp’ is UTC, so if this code were to run from a system on the East coast of the US the time differential would actually be the past 6 hours because EST is (currently) UTC-5 and we’re subtracting another hour on top of that.

One way to prevent something like that from happening would be to use code like this:

one_hour_ago = datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(hours=1)
start_time = one_hour_ago.strftime("%Y-%m-%dT%H:%M:%S")+"Z"

A couple things to keep in mind:

1. The UI can be configured to show the data in local time but it’s doing the calculations for you in the background. The actual data is stored with UTC timestamps and that’s the data that’s in the API.
2. If there’s ever an issue with the filtering syntax, the API typically returns data without applying the filter. So, if you were to see something that looks like more than the specific slice you were looking for, try removing filters to see if you get around the same number of total hits and then start checking the syntax of the removed filters.

Which timestamp is best to use:

The most common timestamp that’s used is the ‘updated_timestamp’, because most customers/partners want to get any updates that happen to the detection since it was created. While this can result in the detection being pulled in again, the modified information is seen as being worth it. The ‘updated_timestamp’ field is also in UTC so you would want to use a calculation like the one above for the value.

A better API endpoint to use:

The current process you’re using is fine but if you’re going to be pulling less than 1,000 events at a time then I’d recommend using the Combined API Endpoint. This will allow you to pull up to 1,000 event details without having to first pull the IDs, essentially it’s going to cut the API calls (and the required coding) in half.