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

# Timestamp

> A calendar date including time information, stored in UTC

Timestamp attributes represent a single, universal moment in time using the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Time information is stored with nanosecond precision, and UTC is the assumed timezone if one is not provided. Timestamp values will always be returned in UTC.

Every Attio object has a `created_at` timestamp attribute, but users can also create their own custom timestamp attributes.

All timestamp attributes are single-select.

### Reading values

Timestamp attributes have a single property, `value` (string).

<CodeGroup>
  ```jsonc Example: 24th November, 2023 theme={"system"}
  {
    "active_from": "2023-04-03T15:21:06.447000000Z",
    "active_until": null,
    "created_by_actor": {
      /*...*/
    },
    "attribute_type": "date",
    "value": "2023-11-24T15:17:48.000000000Z"
  }
  ```
</CodeGroup>

### Writing values

Input values will be coerced into the full format. UTC is assumed if not specified. For example, the following input values would all be coerced to `"2023-01-02T13:00:00.000000000Z"`:

* `"2023"`
* `"2023-01"`
* `"2023-01-02"`
* `"2023-01-02T13:00"`
* `"2023-01-02T13:00:00"`
* `"2023-01-02T13:00:00.000000000"`
* `"2023-01-02T15:00:00.000000000+02:00`

To write timestamp attribute values, you should specify the `value` property:

You may also pass an object with a single property, `value`.

<CodeGroup>
  ```Text Using string theme={"system"}
  {
    "my_timestamp_attribute": "2019-01-17T15:17:48.000000000Z"
  }
  ```

  ```json Using object theme={"system"}
  {
    "my_timestamp_attribute": [
      {
        "value": "2019-01-17T15:17:48.000000000Z"
      }
    ]
  }
  ```
</CodeGroup>

### Filtering

Timestamp attribute values can be filtered by their value. Unlike when writing timestamp values, both date and time components must be specified.

You can filter for an exact timestamp using the implicit syntax, or use the `$eq`,`$gt`,`$gte`,`$lt`,`$lte` operators with the explicit syntax.

<CodeGroup>
  ```json Companies created on 2023-11-24 at 15:34:07.111222333Z theme={"system"}
  {
    "filter": {
      "created_at": "2023-11-24T15:34:07.111222333Z"
    }
  }
  ```

  ```json ... after the year 2000 theme={"system"}
  {
    "filter": {
      "created_at": {
        "value": {
          "$gte": "2000-01-01T00:00:00Z"
        }
      }
    }
  }
  ```
</CodeGroup>

Since timestamps are stored with nanosecond precision, it is often undesirable to look for an exact timestamp if you're trying to filter records with a lower precision, e.g. in a given hour or day. Here, you should use two operators to set the upper and lower bounds of the query, remembering to use the inclusive `$gte` for the earlier bound and the exclusive `$lt` for the upper bound:

<CodeGroup>
  ```json Companies created between 8am and 9am theme={"system"}
  {
    "filter": {
      "created_at": {
        "$gte": "2023-11-24T08:00:00Z",
        "$lt": "2023-11-24T09:00:00Z"
      }
    }
  }
  ```

  ```json ... on 24th November theme={"system"}
  {
    "filter": {
      "created_at": {
        "$gte": "2023-11-24T00:00:00Z",
        "$lt": "2023-11-25T00:00:00Z"
      }
    }
  }
  ```
</CodeGroup>