---
title: "Get the closest event ID to the given timestamp"
method: GET
path: "/_matrix/client/v1/rooms/{roomId}/timestamp_to_event"
tags: ["Room participation"]
---

# Get the closest event ID to the given timestamp

`GET /_matrix/client/v1/rooms/{roomId}/timestamp_to_event`

## Request

- Base URL: `https://matrix.org`
- URL: `https://matrix.org/_matrix/client/v1/rooms/{roomId}/timestamp_to_event`
- Auth: one of:
  - API key in query parameter `access_token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/matrix/apis/matrix-client-server-api/docs/_matrix/client/v1/rooms/:roomId/timestamp_to_event/get.ts> (a function with typed inputs; its response is checked against the schema)

Get the ID of the event closest to the given timestamp, in the
direction specified by the `dir` parameter.

If the server does not have all of the room history and does not have
an event suitably close to the requested timestamp, it can use the
corresponding [federation endpoint](https://spec.matrix.org/v1.19/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid)
to ask other servers for a suitable event.

After calling this endpoint, clients can call
[`/rooms/{roomId}/context/{eventId}`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidcontexteventid)
to obtain a pagination token to retrieve the events around the returned event.

The event returned by this endpoint could be an event that the client
cannot render, and so may need to paginate in order to locate an event
that it can display, which may end up being outside of the client's
suitable range.  Clients can employ different strategies to display
something reasonable to the user.  For example, the client could try
paginating in one direction for a while, while looking at the
timestamps of the events that it is paginating through, and if it
exceeds a certain difference from the target timestamp, it can try
paginating in the opposite direction.  The client could also simply
paginate in one direction and inform the user that the closest event
found in that direction is outside of the expected range.

## Path parameters

- `roomId` string, mx-room-id, required

## Query parameters

- `ts` integer, required
- `dir` 'f' | 'b', required

## Response `200`

An event was found matching the search parameters.

- object
  - `event_id` string, mx-event-id, required: The ID of the event found
  - `origin_server_ts` integer, required: The event's timestamp, in milliseconds since the Unix epoch. This makes it easy to do a quick comparison to see if the `event_id` fetched is too far out of range to be useful for your use case.

## Other responses

- `404`: No event was found.
- `429`: This request was rate-limited.

---

[API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)