---
search:
  tags:
    - Topics
    - POST
seo:
  description: >-
    Anchor the data one session holds for one topic to wall-clock… Reference for
    the POST /v2/topics/id/{topic_id}/unix-offset endpoint in the Roboto REST
    API.
sidebar:
  label: Set topic unix offset
  badge: POST
title: Set topic unix offset
type: openapi-operation
---
Anchor the data one session holds for one topic to wall-clock time.

``unix_epoch_offset_ns`` is added to the stored timestamps of every partition of this topic
that the session's membership claims admit, so they read as wall-clock time
(``session_time_ns = stored_time_ns + unix_epoch_offset_ns``). This is the write for a session
whose data all starts from one time 0 but is stored apart: chunked across several files, or
packed into slices of one shared file. All of its partitions move in one transaction, so a
failure leaves every one of them at the offset it already had.

The offset is an integer of nanoseconds since the Unix epoch, or any time
``roboto.time.to_epoch_nanoseconds`` reads: a float or numeric string is seconds, and an ISO 8601
string is that instant.

The offsets are stored on the partitions' timeline extents, which belong to the files rather than to
the session: any other session holding the same data sees the same anchor. A membership's declared
time range is stored in anchored time, so it moves with its data, but only when everything the
membership claims moved by one distance; a membership whose claim also covers data this write
leaves alone (another topic in the same file or slice) keeps its declared range. To move a
whole session at once, use the session's own unix-offset endpoint, or declare its ``anchor_ns``
at ingest; the file's timeline-offsets endpoint with no selector does the same in one call only
when the whole session is one whole file.

Returns the updated timeline extent records.

The caller must hold session-view access in the org that owns the session, and edit access to
every file behind the data being written. An unknown session yields a 404, and one the caller
cannot view yields a 401. The topic is reached only through the session's partitions, so both an
unknown topic and one the session holds no data for yield a 404.

An offset yields a 400 when it cannot be read as a time, when it does not fall after the Unix epoch and below
2**63 ns, or when it would move the data it reaches, or a time range declared over that data, before the Unix
epoch or past the largest storable instant (2**63 - 1 ns). A concurrent writer adding data to the session
yields a 409; retry the request.

### Access control
 - Restricted tokens need the API scope `api.everything_else`

`POST /v2/topics/id/{topic_id}/unix-offset`