Skip to main content
POST/realtime/replay

Replay Realtime Events

Returns one page of past events for a topic.

The request body accepts topic (required), fromSequence, untilSequence, afterAuditEventId and limit (at most 10,000 events per call).

Only the audit tail keeps a ledger: for every other project topic the answer has no events and resync: "reread-source", so re-read current state through the data API, then subscribe.

An unrecognised topic returns K9O_INVALID_FILTER (400).

For the live audit tail (audit.project.*), the replay reads the project's audit log in order, so it includes every audit event, warden.checkpoint included: pass afterAuditEventId (the last auditEventId you received) or fromSequence.

Each event carries the same five fields as a live frame plus its sequence.

The audit tail needs the audit log's access (K9O_RBAC_DENY (403) otherwise).

An afterAuditEventId that is not in the log returns K9O_INVALID_CURSOR (400).

Parameters
projectSlug *path

The project's slug, as in /@<projectSlug>/….

Request body
topic *string

The topic to catch up on: an exact topic or a prefix ending in .*.

Only audit.project.* (or audit.project.<type>) keeps a ledger; any other project topic answers with no events and resync: "reread-source".

Example: "audit.project.*"
fromSequenceany

audit.project.* only: start at this ledger sequence (inclusive).

An integer or a string of digits; 0 by default.

Example: 0
One of: integer
or: string
untilSequenceany

audit.project.* only: stop at this ledger sequence (inclusive).

An integer or a string of digits; the end of the ledger by default.

Example: 5000
One of: integer
or: string
limitinteger

The most events to return, 1 to 10000.

Page on with nextCursor while hasMore is true.

Example: 100
afterAuditEventIdstring

audit.project.* only: return the events after this one, the auditEventId of the last live frame or replayed event received.

An id that is not in the audit log answers 400 K9O_INVALID_CURSOR.

Example: "evt_4fQ2nX8pLm1z"
Responses
HTTPK9O CodeDescription
200Success
400K9O_INVALID_FILTERThe replay filter contains an unsupported operator and could not be processed.
400K9O_INVALID_CURSORafterAuditEventId is not an event in this project's audit log.
401K9O_SESSION_EXPIREDYour session has expired; sign in again before requesting an event replay.
401K9O_INVALID_CREDENTIALSThe credentials provided are not valid; the replay request was rejected.
403K9O_ACCESS_DENIEDYour role does not permit requesting a replay on this resource.
403K9O_RBAC_DENYThe audit topics (audit.project.*) need GET /audit-log's authority: PROJECT_AUDITOR or PROJECT_ADMIN (or an org admin or owner).
403K9O_IAM_POLICY_DENIEDThe bound IAMPolicy ceiling denies audit_log:query, which the audit topics (audit.project.*) require.
404K9O_COLLECTION_NOT_FOUNDThe collection referenced in the replay request does not exist in this project.
Response body (200)
data *any

The replayed page: the audit log for audit.project.*, or an empty page with resync for any other topic.

One of: object
topic *string

The topic the request named.

Example: "audit.project.*"
events *object[]

The audit events in the requested range, oldest first.

sequence *string

The event's place in the project's audit log (the replay cursor).

Example: "4182"
topic *string

audit.project.<type>.

Example: "audit.project.data.write.access.update"
eventType *string

The audit event type, the same as payload.type.

Example: "data.write.access.update"
payload *object

The same five fields as a live audit frame.

Read the full event from the audit log by auditEventId.

auditEventId *string

The audit event's id; pass the last one received as afterAuditEventId to resume.

Example: "evt_4fQ2nX8pLm1z"
type *string

The audit event type.

Example: "data.write.access.update"
actorType *"user" | "extension" | "end_user" | "token" | "agent" | "service" | "system" | "other"

What kind of principal acted.

occurredAt *string <date-time>

When the audited action happened.

Example: "2026-11-02T14:05:31.512Z"
outcome *any

How the action ended; null when the event records no outcome.

Example: "success"
occurredAt *string <date-time>

When the audited action happened.

Example: "2026-11-02T14:05:31.512Z"
nextCursor *any

Pass as fromSequence to read the next page; null at the end of the log.

Example: "4283"
One of: string
or: null
hasMore *boolean

Whether more events follow this page.

Example: true
or: object
topic *string

The topic the request named.

Example: "audit.project.*"
events *any[]

Always empty: this topic keeps no ledger.

nextCursor *null

Always null.

hasMore *false

Always false.

resync *"reread-source"

Re-read current state through the data API, then subscribe.

meta *object

Request metadata: cost, timing and correlation ids.

cost *object

Metered usage for this request; empty when nothing was metered.

timing *object
gatewayMs *number
totalMs *number
context *object
requestId *string
traceId *string
projectIdstring
warningsobject[]
code *string
message *string
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.realtime.replay({
  topic: 'audit.project.*',
  afterAuditEventId: 'evt_4fQ2nX8pLm1z',
  limit: 100
})

Showing example in TypeScript

Request example
{
  "topic": "audit.project.*",
  "afterAuditEventId": "evt_4fQ2nX8pLm1z",
  "limit": 100
}
Response example (200)
{
  "data": {
    "topic": "audit.project.*",
    "events": [
      {
        "sequence": "4182",
        "topic": "audit.project.data.write.access.update",
        "eventType": "data.write.access.update",
        "payload": {
          "auditEventId": "evt_4fQ2nX8pLm1z",
          "type": "data.write.access.update",
          "actorType": "user",
          "occurredAt": "2026-11-02T14:05:31.512Z",
          "outcome": "success"
        },
        "occurredAt": "2026-11-02T14:05:31.512Z"
      }
    ],
    "nextCursor": "4283",
    "hasMore": true
  },
  "meta": {
    "timing": {
      "gatewayMs": 0,
      "totalMs": 0
    },
    "context": {
      "requestId": "string",
      "traceId": "string",
      "projectId": "string"
    },
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ]
  }
}

More in Realtime Feeds & Streams