Datetimes

Date and timestamp support

Note that event datetimes sent via the legacy v1/v2 endpoints support Unix timestamps in addition to datetime ISO 8601 formats. However, our new APIs do not support Unix timestamps. It is recommended that you convert the Unix timestamp to a supported ISO 8601 format. See the MDN docs on the toISOString() method for more details on conversion.

Datetime formatting

All datetimes across all new APIs in URLs, requests, and response bodies must use the ISO 8601 RFC 3339 format, such as YYYY-MM-DDTHH:MM:SS.[mmm]. Note that the letters used in the datetime syntax must always be uppercase. Some examples include:

2023-08-15T12:30:00
2023-08-15T12:30:00Z
2023-08-15 12:30:00Z
2023-08-15T12:30:00+03:00

For more information on recognized formats, refer to our acceptable date and timestamp formats guide for profile and event properties.

URI encoding

Datetimes can contain non-URL-safe characters. To combat this, we recommend that you always URI-encode your datetime values. Refer to the MDN docs on encodeURIComponent for more details.

Example request and response

In this example, we have requested all events that have a datetime greater than 2023-08-07T12:30:00.710Z:

curl --request GET \
     --url 'https://a.klaviyo.com/api/events/?filter=greater-than(datetime,2023-08-07T12:30:00.710Z)' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2023-07-15'

{
    "data": [
        {
            "type": "event",
            "id": "4vGfpcpPRGL",
            "attributes": {
                "timestamp": 1692028246,
                "event_properties": {
                    "custom_value": "newer event time value",
                    "$event_id": "YjpZcE"
                },
                "datetime": "2023-08-14 15:50:46+00:00",
                "uuid": "55084f00-3aba-11ee-8001-a3e96a3d92dc"
            },
            "relationships": {
                "profile": {
                    "data": {
                        "type": "profile",
                        "id": "01H7TBW70G8RYXHF9D91K4W72J"
                    },
                    "links": {
                        "self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/relationships/profile/",
                        "related": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/profile/"
                    }
                },
                "metric": {
                    "data": {
                        "type": "metric",
                        "id": "TQpx2b"
                    },
                    "links": {
                        "self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/relationships/metric/",
                        "related": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/metric/"
                    }
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/events/4vGfpcpPRGL/"
            }
        },
        {
            "type": "event",
            "id": "4uQsGyFKUGn",
            "attributes": {
                "timestamp": 1691523702,
                "event_properties": {
                    "custom_value": "custom val",
                    "$event_id": "1691523702"
                },
                "datetime": "2023-08-08 19:41:42+00:00",
                "uuid": "995f9f00-3623-11ee-8001-b91e24a90599"
            },
            "relationships": {
                "profile": {
                    "data": {
                        "type": "profile",
                        "id": "01H6PJY17J72TV4EWXZPS1XYX7"
                    },
                    "links": {
                        "self": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/relationships/profile/",
                        "related": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/profile/"
                    }
                },
                "metric": {
                    "data": {
                        "type": "metric",
                        "id": "QV8sPg"
                    },
                    "links": {
                        "self": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/relationships/metric/",
                        "related": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/metric/"
                    }
                }
            },
            "links": {
                "self": "https://a.klaviyo.com/api/events/4uQsGyFKUGn/"
            }
        }
    ],
    "links": {
        "self": "https://a.klaviyo.com/api/events/?filter=greater-than(datetime,2023-08-07T12:30:00.710Z)",
        "next": null,
        "prev": null
    }
}

Date and timestamp support

Datetime formatting

URI encoding

Example request and response

Additional resources