---
title: "subscriptions"
description: "The subscriptions namespace — the engine's Luau API reference for subscriptions."
section: "API Reference"
slug: "api-subscriptions"
canonical: "https://origozero.ai/docs/api-subscriptions"
updated: "2026-09-05T23:13:47.284532656+00:00"
tags: ["api", "reference"]
---

# subscriptions

The `subscriptions` namespace — 13 functions.

## globals/subscriptions/cancel {#globals-subscriptions-cancel}

```lua
subscriptions.cancel(id: string) -> boolean
```

Cancel a subscription by id: disconnects the live connection
immediately and marks the row cancelled. Returns true when a live
subscription was cancelled, false for an unknown or
already-disconnected id.

**Parameters**

- `id` `string` — Subscription id to cancel.

**Returns** `boolean` — True when a live subscription was disconnected.

```lua
subscriptions.cancel(conn.id)
```

## globals/subscriptions/get {#globals-subscriptions-get}

```lua
subscriptions.get(id: string) -> SubscriptionRow?
```

One subscription row by id, or nil when the id is unknown (never
tracked, or evicted after its publisher was destroyed).

**Parameters**

- `id` `string` — Subscription id (`conn.id`, or a `/zero/runtime/events/subscriptions/` entry).

**Returns** `SubscriptionRow?` — The subscription row, or nil.

```lua
local row = subscriptions.get(conn.id); print(row and row.deliveries)
```

## globals/subscriptions/list {#globals-subscriptions-list}

```lua
subscriptions.list(filter: SubscriptionFilter?) -> { SubscriptionRow }
```

Every tracked subscription row, optionally filtered by publisher
instance id, publisher entity id, event name, and/or connected state.

**Parameters**

- `filter` `SubscriptionFilter` _(optional)_ — Optional filter table.

**Returns** `{ SubscriptionRow }` — Array of subscription rows.

```lua
for _, s in ipairs(subscriptions.list({ connected = true })) do print(s.id, s.event, s.deliveries) end
```

## globals/subscriptions/publishers {#globals-subscriptions-publishers}

```lua
subscriptions.publishers() -> { PublisherRow }
```

Every live event publisher: component instance, entity, and
per-event fire stats (fires happen whether or not anyone subscribes)
plus current subscriber ids.

**Returns** `{ PublisherRow }` — Array of publisher rows.

```lua
for _, p in ipairs(subscriptions.publishers()) do print(p.component, p.entityName) end
```

## modules/subscriptions/README {#modules-subscriptions-readme}

```lua
require("@builtin/modules/api/engine/subscriptions") -- subscriptions (also available as global 'subscriptions')
```

Runtime inspection and cancellation of component-event subscriptions. Public Luau surface over the `__event_inspect_*` / `__event_track_*` Internal FFI globals; the same data is browsable at `/zero/runtime/events/`.

Usage: local subscriptions = require("@builtin/modules/api/engine/subscriptions")
Also available as global: subscriptions

## modules/subscriptions/cancel {#modules-subscriptions-cancel}

```lua
cancel(id: string): boolean
```

Cancel a subscription by id: disconnects the live connection
immediately and marks the row cancelled. Returns true when a live
subscription was cancelled, false for an unknown or
already-disconnected id.

**Parameters**

- `id` `string` — Subscription id to cancel.

```lua
subscriptions.cancel(conn.id)
```

## modules/subscriptions/get {#modules-subscriptions-get}

```lua
get(id: string): SubscriptionRow?
```

One subscription row by id, or nil when the id is unknown (never
tracked, or evicted after its publisher was destroyed).

**Parameters**

- `id` `string` — Subscription id (`conn.id`, or a `/zero/runtime/events/subscriptions/` entry).

```lua
local row = subscriptions.get(conn.id); print(row and row.deliveries)
```

## modules/subscriptions/list {#modules-subscriptions-list}

```lua
list(filter: SubscriptionFilter?): { SubscriptionRow }
```

Every tracked subscription row, optionally filtered by publisher
instance id, publisher entity id, event name, and/or connected state.

**Parameters**

- `filter` `SubscriptionFilter?` _(optional)_ — Optional filter table.

```lua
for _, s in ipairs(subscriptions.list({ connected = true })) do print(s.id, s.event, s.deliveries) end
```

## modules/subscriptions/publishers {#modules-subscriptions-publishers}

```lua
publishers(): { PublisherRow }
```

Every live event publisher: component instance, entity, and
per-event fire stats (fires happen whether or not anyone subscribes)
plus current subscriber ids.

```lua
for _, p in ipairs(subscriptions.publishers()) do print(p.component, p.entityName) end
```

## typed/builtin//modules/api/engine/subscriptions/subscriptions/cancel {#typed-builtin-modules-api-engine-subscriptions-subscriptions-cancel}

```lua
subscriptions.cancel(id: string) -> boolean
```

Cancel a subscription by id: disconnects the live connection
immediately and marks the row cancelled. Returns true when a live
subscription was cancelled, false for an unknown or
already-disconnected id.

**Parameters**

- `id` `string` — Subscription id to cancel.

**Returns** `boolean` — True when a live subscription was disconnected.

```lua
subscriptions.cancel(conn.id)
```

## typed/builtin//modules/api/engine/subscriptions/subscriptions/get {#typed-builtin-modules-api-engine-subscriptions-subscriptions-get}

```lua
subscriptions.get(id: string) -> SubscriptionRow?
```

One subscription row by id, or nil when the id is unknown (never
tracked, or evicted after its publisher was destroyed).

## typed/builtin//modules/api/engine/subscriptions/subscriptions/list {#typed-builtin-modules-api-engine-subscriptions-subscriptions-list}

```lua
subscriptions.list(filter: SubscriptionFilter?) -> { SubscriptionRow }
```

Every tracked subscription row, optionally filtered by publisher
instance id, publisher entity id, event name, and/or connected state.

## typed/builtin//modules/api/engine/subscriptions/subscriptions/publishers {#typed-builtin-modules-api-engine-subscriptions-subscriptions-publishers}

```lua
subscriptions.publishers() -> { PublisherRow }
```

Every live event publisher: component instance, entity, and
per-event fire stats (fires happen whether or not anyone subscribes)
plus current subscriber ids.

**Returns** `{ PublisherRow }` — Array of publisher rows.

```lua
for _, p in ipairs(subscriptions.publishers()) do print(p.component, p.entityName) end
```