# getUnixAgo

:::caution[Unreleased]
Not in `@northguild/gmt` 1.20.0 on npm yet. It is on `main` and ships in the next release.
:::

## Signature

```ts
getUnixAgo(units: Partial<Record<keyof DurationLike, number>>, options?: { epochUnit?: UnixUnit; }): number | null
```

Return the Unix epoch before now, counted from the current time in UTC.

- Reads the clock once, after `units` and `options` are checked.
- `units` is an object of unit amounts, such as `{ days: 90 }`. A duration string returns null, and so does a fractional amount: write `{ hours: 36 }` for a day and a half.
- Lengths are unsigned: a negative amount returns null. `getUnixIn` counts forward.
- `{ days: 0 }` is a valid length and gives now.
- Calendar units count in UTC, so the result does not change with the server's zone, and a missing day clamps to the end of the month, as `subtractUnix` does. For another zone's wall clock, use `getZonedAgo` and convert.
- A `timeZone` member is not read, as `getUnixNow` reads none.
- Each call reads the clock. To pin the start, use `subtractUnix(getUnixNow(), units)`.

## Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `units` | `Partial<Record<keyof DurationLike, number>>` | unit amounts, such as `{ days: 90 }`; never negative |

## Options

**options**

optional: the unit of the result

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `epochUnit?` | `"seconds"` \| `"milliseconds"` \| `"second"` \| `"millisecond"` ([`UnixUnit`](/gmt/reference/types/UnixUnit)) | `"milliseconds"` | The unit of the returned epoch: `"seconds"` or `"milliseconds"`, singular or plural. Any other value returns `null`. Seconds floor toward −∞, and a JWT `exp` needs them: the default is milliseconds, and a millisecond `exp` reads as a date far in the future. |

## Returns

the Unix epoch, or null for invalid `units`, a negative amount, invalid `options` or a result outside Temporal's range

## Related types

- [`DateTimeDurationUnit`](/gmt/reference/types/DateTimeDurationUnit)
- [`UnixUnit`](/gmt/reference/types/UnixUnit)

## Examples

```ts
import { getUnixAgo } from "@northguild/gmt/unix/get";

getUnixAgo({ days: 90 }, { epochUnit: "seconds" }) // 1805284800 (90 days back, from a clock at 2027-06-15T12:00:00Z)
```

## Source

[unix/get/getUnixAgo.ts](https://github.com/northguild/gmt/blob/main/packages/gmt/src/unix/get/getUnixAgo.ts)