---
source_url: https://www.pubnub.com/docs/sdks/lua/api-reference/storage-and-playback
title: Storage and Playback API for Lua SDK
updated_at: 2026-06-19T11:37:47.264Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Storage and Playback API for Lua SDK

Message Persistence gives you real-time access to the history of messages published to PubNub. Each message is timestamped to the nearest 10 nanoseconds and stored across multiple availability zones in several geographic locations. You can encrypt stored messages with AES-256 so they are not readable on PubNub’s network. For details, see [Message Persistence](https://www.pubnub.com/docs/general/storage).

You control how long messages are stored through your account’s retention policy. Options include: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.

You can retrieve the following:

* Messages
* Message reactions
* Files (using the File Sharing API)

## History

:::warning Requires Message Persistence
Enable Message Persistence for your key in the [Admin Portal](https://admin.pubnub.com/). See how to [enable add-on features](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-).
:::

This function fetches historical messages of a channel.

You can control how messages are returned and in what order.

* Search for messages starting on the newest end of the timeline (default behavior - `reverse` = `false`).
* Search for messages from the oldest end of the timeline by setting `reverse` to `true`.
* Page through results by providing a `start` OR `end` timetoken.
* Retrieve a slice of the timeline by providing both a `start` AND `end` timetoken.
* Limit the number of messages to a specific quantity using the `count` parameter.

:::tip Start & End parameter usage clarity
If only the `start` parameter is specified (without `end`), you receive messages that are older than and up to that `start` timetoken value. If only the `end` parameter is specified (without `start`) you receive messages that match that `end` timetoken value and newer. Specifying values for both `start` and `end` parameters returns messages between those timetoken values (inclusive on the `end` value). Keep in mind that you still receive a maximum of 100 messages even if more messages meet the timetoken values. Iterative calls to history adjusting the `start` timetoken are necessary to page through the full set of results if more than 100 messages meet the timetoken values.
:::

### Method(s)

Use the following method(s) in the Lua SDK:

```lua
pubnub_obj:history(params)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| params | table | Yes |  | Table of `history` parameters. See [History Parameters](#history-parameters) for more details. |

#### History parameters

| Parameter | Description |
| --- | --- |
| `Channel` *Type: stringDefault: `none` | The channel to get history for. |
| `callback` *Type: function(r)Default: `none` | The function to call with received history. |
| `error`Type: function(r)Default: `function(r) end` | The function to call on failure, with result. |
| `start`Type: integer or stringDefault: `none` | The timetoken to start history from. |
| `stop`Type: integer or stringDefault: `none` | The timetoken to stop history at. |
| `reverse`Type: booleanDefault: `false` | Whether to get the history in reverse (from chronological) order. |
| `count`Type: integerDefault: `10` | Maximum number of messages to get in history (cannot be more than 100). |

:::tip
Using the
reverse
parameter
Messages are always returned sorted in ascending time direction from history regardless of `reverse`. The `reverse` direction matters when you have more than 100 (or `count`, if it's set) messages in the time interval, in which case `reverse` determines the end of the time interval from which it should start retrieving the messages.
:::

### Sample code

Retrieve the last 100 messages on a channel:

```lua
pubnub_obj:history({
    channel = "demo",
    count = 100,
    callback = function(response)
        textout(response)
    end,
    error = function (response)
        textout(response)
    end
})
```

## Terms in this document

* **Message** - A unit of data transmitted between clients or between a client and a server in PubNub, containing information such as text, binary data, or structured data formats like JSON. Messages are sent over channels and can be tracked for delivery and read status.
* **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.