Use the ago function in APL to subtract a given timespan from the current UTC clock time. The function returns a datetime value equal to now() - timespan.
You can use ago to create relative time filters that adapt automatically to the current time. This is especially useful for dashboards, alerts, and ad-hoc investigations where you want to focus on recent activity without hardcoding timestamps.
Use it when you want to:
- Filter events that occurred within a recent time window.
- Create dynamic time-based thresholds for alerting or anomaly detection.
- Compare current activity against a rolling baseline period.
For users of other query languages
If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.
In Splunk SPL, you typically use time modifiers such as earliest=-6h or relative_time(now(), "-6h@h") to filter events by relative time. In APL, the ago function directly subtracts a timespan from the current UTC time and returns a datetime you can use in filters.
... | where _time > ago(6h)In ANSI SQL, you typically subtract an interval from the current timestamp using expressions such as CURRENT_TIMESTAMP - INTERVAL '6' HOUR or DATEADD(HOUR, -6, GETDATE()). In APL, the ago function achieves the same result with a concise syntax.
['dataset']
| where _time > ago(6h)Usage
Syntax
ago(timespan)Parameters
| Name | Type | Description |
|---|---|---|
| timespan | timespan |
The timespan to subtract from the current UTC time. |
Returns
A datetime value equal to now() - timespan.
Use case examples
Filter HTTP logs from the last 6 hours and count requests by status code.
Query
['sample-http-logs']
| where _time > ago(6h)
| summarize count() by statusOutput
| status | count_ |
|---|---|
| 200 | 1523 |
| 404 | 87 |
| 500 | 34 |
This query filters log entries to the last 6 hours and groups them by HTTP status code to give a quick overview of recent traffic health.
Find slow traces from the last day and count them by service name.
Query
['otel-demo-traces']
| where _time > ago(1d)
| where duration > 1s
| summarize count() by ['service.name']Output
| ['service.name'] | count_ |
|---|---|
| frontend | 42 |
| checkout | 15 |
| cart | 8 |
This query identifies services with slow spans (over 1 second) in the last 24 hours, helping you pinpoint performance bottlenecks.
Detect high error rates in the last 12 hours by counting client and server errors per hour.
Query
['sample-http-logs']
| where _time > ago(12h)
| where toint(status) >= 400
| summarize error_count = count() by bin(_time, 1h)Output
| _time | error_count |
|---|---|
| 2025-01-15T00:00:00Z | 12 |
| 2025-01-15T01:00:00Z | 45 |
| 2025-01-15T02:00:00Z | 9 |
This query bins error responses into hourly buckets over the last 12 hours, making it easy to spot sudden spikes in failures.
List of related functions
- now: Returns the current UTC time. Use
nowwhen you need the absolute current time rather than a relative offset. - datetime_add: Adds a specified number of date parts to a datetime. Use when you need to shift a datetime forward or backward by a specific calendar unit.
- datetime_diff: Calculates the difference between two datetime values. Use when you need to measure elapsed time between events.
- startofday: Returns the start of the day for a datetime, useful for day-level binning.
- endofday: Returns the end of the day for a datetime.