> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://axiom.co/docs/feedback

```json
{
  "path": "/apl/scalar-functions/datetime-functions/ago",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# ago

> This page explains how to use the ago function in APL.

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.

<AccordionGroup>
  <Accordion title="Splunk SPL users">
    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.

    <CodeGroup>
      ```sql Splunk example theme={null}
      ... | where _time > relative_time(now(), "-6h@h")
      ```

      ```kusto APL equivalent theme={null}
      ... | where _time > ago(6h)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    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.

    <CodeGroup>
      ```sql SQL example theme={null}
      SELECT * FROM events WHERE timestamp_column > CURRENT_TIMESTAMP - INTERVAL '6' HOUR;
      ```

      ```kusto APL equivalent theme={null}
      ['dataset']
      | where _time > ago(6h)
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Usage

### Syntax

```kusto theme={null}
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

<Tabs>
  <Tab title="Log analysis">
    Filter HTTP logs from the last 6 hours and count requests by status code.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | where _time > ago(6h)
    | summarize count() by status
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20where%20_time%20%3E%20ago\(6h\)%20%7C%20summarize%20count\(\)%20by%20status%22%7D)

    **Output**

    | 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.
  </Tab>

  <Tab title="OpenTelemetry traces">
    Find slow traces from the last day and count them by service name.

    **Query**

    ```kusto theme={null}
    ['otel-demo-traces']
    | where _time > ago(1d)
    | where duration > 1s
    | summarize count() by ['service.name']
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20where%20_time%20%3E%20ago\(1d\)%20%7C%20where%20duration%20%3E%201s%20%7C%20summarize%20count\(\)%20by%20%5B'service.name'%5D%22%7D)

    **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.
  </Tab>

  <Tab title="Security logs">
    Detect high error rates in the last 12 hours by counting client and server errors per hour.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | where _time > ago(12h)
    | where toint(status) >= 400
    | summarize error_count = count() by bin(_time, 1h)
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20where%20_time%20%3E%20ago\(12h\)%20%7C%20where%20toint\(status\)%20%3E%3D%20400%20%7C%20summarize%20error_count%20%3D%20count\(\)%20by%20bin\(_time%2C%201h\)%22%7D)

    **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.
  </Tab>
</Tabs>

## List of related functions

* [now](/apl/scalar-functions/datetime-functions/now): Returns the current UTC time. Use `now` when you need the absolute current time rather than a relative offset.
* [datetime\_add](/apl/scalar-functions/datetime-functions/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](/apl/scalar-functions/datetime-functions/datetime-diff): Calculates the difference between two datetime values. Use when you need to measure elapsed time between events.
* [startofday](/apl/scalar-functions/datetime-functions/startofday): Returns the start of the day for a datetime, useful for day-level binning.
* [endofday](/apl/scalar-functions/datetime-functions/endofday): Returns the end of the day for a datetime.