---
source_url: https://www.pubnub.com/docs/sdks/python/api-reference/storage-and-playback
title: Message Persistence API for Python SDK
updated_at: 2026-06-05T11:13:07.220Z
sdk_name: PubNub Python SDK
sdk_version: 10.6.3
---

> 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


# Message Persistence API for Python SDK

PubNub Python SDK, use the latest version: 10.6.3

Install:

```bash
pip install pubnub@10.6.3
```

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)

:::note Request execution and return values
You can decide whether to perform the Python SDK operations synchronously or asynchronously.
* .sync() returns an Envelope object, which has two fields: Envelope.result, whose type differs for each API, and Envelope.status of type PnStatus. 1pubnub.publish() \2 .channel("myChannel") \3 .message("Hello from PubNub Python SDK") \4 .sync()
* .pn_async(callback) returns None and passes the values of Envelope.result and Envelope.status to a callback you must define beforehand. 1def my_callback_function(result, status):2 print(f'TT: {result.timetoken}, status: {status.category.name}')3 4pubnub.publish() \5 .channel("myChannel") \6 .message("Hello from PubNub Python SDK") \7 .pn_async(my_callback_function)
:::

## Fetch 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-).
:::

Fetch historical messages from one or more channels. Use `include_message_actions` to include message actions.

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

* If you specify only the `start` parameter (without `end`), you receive messages older than the `start` timetoken.
* If you specify only the `end` parameter (without `start`), you receive messages from that `end` timetoken and newer.
* If you specify both `start` and `end`, you retrieve messages between those timetokens (inclusive of the `end` value).

You can receive up to 100 messages for a single channel. For multiple channels (up to 500), you can receive up to 25 messages per channel. If more messages match the time range, make iterative calls and adjust the `start` timetoken to page through the results.

### Method(s)

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

```python
pubnub.fetch_messages() \
    .channels(List) \
    .maximum_per_channel(Integer) \
    .start(Integer) \
    .end(Integer) \
    .include_message_actions(Boolean) \
    .include_meta(Boolean)
    .include_message_type(Boolean) \
    .include_custom_message_type(Boolean) \
    .include_uuid(Boolean) \
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| channels | List<string> | Yes |  | Specifies the channels for which to return history. Maximum of 500 channels are allowed. |
| maximum_per_channel | Integer | Optional | `25 or 100` | Specifies the number of historical messages to return. If `include_message_actions` is `True`, method is limited to single channel and 25 is the default (and maximum) value; otherwise, default and maximum is 100 for a single channel, or 25 for multiple channels. |
| start | Integer | Optional |  | Timetoken delimiting the *exclusive* start of the time slice from which to pull messages. |
| end | Integer | Optional |  | Timetoken delimiting the *inclusive* end of the time slice from which to pull messages. |
| include_message_actions | Boolean | Optional | `False` | Set to `True` to retrieve history messages with their associated message actions. If you include message actions, the `fetch_messages()` method is limited to one channel only. |
| include_meta | Boolean | Optional | `False` | Whether to include message metadata within response or not. |
| include_message_type | Boolean | Optional |  | Indicates whether to retrieve messages with PubNub message type. For more information, refer to [Retrieving Messages](https://www.pubnub.com/docs/general/storage#retrieve-messages). |
| include_custom_message_type | Boolean | Optional |  | Indicates whether to retrieve messages with the custom message type. For more information, refer to [Retrieving Messages](https://www.pubnub.com/docs/general/storage#retrieve-messages). |
| include_uuid | Boolean | Optional |  | Whether to include UUID of the sender |

### Sample code

:::tip Reference code
This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.
:::

Retrieve the last message on a channel:

###### Builder Pattern

```python
import os
from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub

def my_fetch_messages_callback(envelope, status):
    if status.is_error():
        print(f"Something went wrong. Error: {status.error_data}")
        return

    print("Fetch Messages Result:\n")
    for message in envelope.channels["my_channel"]:
        print("Message: %s" % message.message)
        print("Meta: %s" % message.meta)
        print("Timetoken: %s" % message.timetoken)

        for action_type in message.actions:
            print("\nMessage Action type: " + action_type)
            for action_value in message.actions[action_type]:
                print("Message Action value: %s" % action_value)
                for action in message.actions[action_type][action_value]:
                    print("Message Action timetoken: %s" % action['actionTimetoken'])
                    print("Message Action uuid: %s" % action['uuid'])

def main():
    # Configuration for PubNub instance
    pn_config = PNConfiguration()
    pn_config.subscribe_key = os.getenv('SUBSCRIBE_KEY', 'demo')
    pn_config.user_id = os.getenv('USER_ID', 'my_custom_user_id')

    # Initialize PubNub client
    pubnub = PubNub(pn_config)

    # Fetch messages
    pubnub.fetch_messages() \
        .channels(["my_channel"]) \
        .maximum_per_channel(1) \
        .include_message_actions(True) \
        .include_meta(True) \
        .include_message_type(True) \
        .include_custom_message_type(True) \
        .include_uuid(True) \
        .pn_async(my_fetch_messages_callback)

if __name__ == "__main__":
    main()
```

###### Named Arguments

```python
message_envelope = pubnub.fetch_messages(channels=["my_channel"], maximum_per_channel=1, include_message_actions=True,
    include_meta=True, include_message_type=True, include_custom_message_type=True, include_uuid=True).sync()

if message_envelope.status.is_error():
    print(f"Something went wrong. Error: {status.error_data}")
else:
        print("Fetch Messages Result:\n")
    for message in message_envelope.result.channels["my_channel"]:
        print(f"Message: {message.message}")
        print(f"Meta: {message.meta}")
        print(f"Timetoken: {message.timetoken}")

        for action_type in message.actions:
            print(f"Message Action type: {action_type}")
            for action_value in message.actions[action_type]:
                print(f"Message Action value: {action_value}")
                for action in message.actions[action_type][action_value]:
                    print(f"Message Action timetoken: {action['actionTimetoken']}")
                    print(f"Message Action uuid: {action['uuid']}")
```

### Returns

The `fetch_messages()` operation returns an `Envelope` which contains the following fields:

| Field | Type | Description |
| --- | --- | --- |
| result | [PNFetchMessagesResult](#pnfetchmessagesresult) | A detailed object containing the result of the operation. |
| status | `PNStatus` | A status object with additional information. |

#### PNFetchMessagesResult

| Method | Description |
| --- | --- |
| `channels`Type: Dictionary | Dictionary of [PNFetchMessageItem](#pnfetchmessageitem) |
| `start_timetoken`Type: Int | Start timetoken |
| `end_timetoken`Type: Int | End timetoken |

#### PNFetchMessageItem

| Method | Description |
| --- | --- |
| `message`Type: String | The message |
| `meta`Type: Any | Meta value |
| `message_type`Type: Any | Type of the message |
| `custom_message_type`Type: Any | Custom type of the message |
| `uuid`Type: String | UUID of the sender |
| `timetoken`Type: Int | Timetoken of the message |
| `actions`Type: List | A 3-dimensional List of message actions, grouped by action type and value |

## Delete messages from 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-).
:::

Remove messages from the history of a specific channel.

:::note Required setting
Enable `Delete-From-History` for your key in the Admin Portal and initialize the SDK with a secret key.
:::

### Method(s)

To `Delete Messages from History` you can use the following method(s) in the Python SDK.

```python
pubnub.delete_messages() \
    .channel(String) \
    .start(Integer) \
    .end(Integer) \
    .sync()
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: StringDefault: n/a | Specifies `channels` to delete messages from. |
| `start`Type: IntegerDefault: n/a | Timetoken delimiting the `start` of time slice (inclusive) to delete messages from. |
| `end`Type: IntegerDefault: n/a | Timetoken delimiting the `end` of time slice (exclusive) to delete messages from. |

### Sample code

#### Builder Pattern

```python
envelope = PubNub(pnconf).delete_messages() \
    .channel("my-ch") \
    .start(123) \
    .end(456) \
    .sync()
```

#### Named Arguments

```python
envelope = pubnub.delete_messages(channels=["my_channel"], start=123, end=456).sync()
```

### Returns

The `delete_messages()` operation doesn't have a return value.

### Other examples

#### Delete specific message from history

To delete a specific message, pass the `publish timetoken` (received from a successful publish) in the `End` parameter and `timetoken +/- 1` in the `Start` parameter. For example, if `15526611838554310` is the `publish timetoken`, pass `15526611838554309` in `Start` and `15526611838554310` in `End` parameters respectively as shown in the following code snippet.

##### Builder Pattern

```python
envelope = PubNub(pnconf).delete_messages() \
    .channel("my-ch") \
    .start(15526611838554309) \
    .end(15526611838554310) \
    .sync()
```

##### Named Arguments

```python
envelope = pubnub.delete_messages(channels="my-ch", start=15526611838554309, end=15526611838554310).sync()
```

## Message counts

:::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-).
:::

Return the number of messages published since the given time. The count is the number of messages with a timetoken greater than or equal to the value in `channel_timetokens`.

:::note Unlimited message retention
Only messages from the last 30 days are counted.
:::

### Method(s)

You can use the following method(s) in the Python SDK:

```python
pn.message_counts() \
    .channel(String) \
    .channel_timetokens(List)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: StringDefault: n/a | The `channels` to fetch the message count. Single channel or multiple channels, separated by comma are accepted. |
| `channel_timetokens` *Type: ListDefault: `null` | A list of timetokens ordered the same way as channels. Timetokens can be str or int type. |

### Sample code

#### Builder Pattern

```python
envelope = pn.message_counts() \
    .channel('unique_1') \
    .channel_timetokens([15510391957007182]) \
    .sync() \
print(envelope.result.channels['unique_1'])
```

#### Named Arguments

```python
envelope = pubnub.message_counts(channels="my-ch", channel_timetokens=[15510391957007182]).sync()
```

### Returns

The `message_counts()` operation returns an `Envelope` which contains the following fields:

| Field | Type | Description |
| --- | --- | --- |
| result | [PNMessageCountResult](#pnmessagecountresult) | A detailed object containing the result of the operation. |
| status | `PNStatus` | A status object with additional information. |

#### PNMessageCountResult

| Field | Type | Description |
| --- | --- | --- |
| `channels` | Dictionary | A dictionary with the number of missed messages for each channel. |

### Other examples

#### Retrieve count of messages using different timetokens for each channel

##### Builder Pattern

```python
envelope = pn.message_counts() \
    .channel('unique_1,unique_100') \
    .channel_timetokens([15510391957007182, 15510391957007184]) \
    .sync()
print(envelope.result.channels)
```

##### Named Arguments

```python
envelope = pubnub.message_counts(channels="unique_1,unique_100",
    channel_timetokens=[15510391957007182, 15510391957007184]).sync()
```

## History (deprecated)

:::warning Requires Message Persistence
This method requires that Message Persistence is [enabled](https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-) for your key in the [Admin Portal](https://admin.pubnub.com/).
:::

:::note Alternative method
This method is deprecated. Use [fetch history](#fetch-history) instead.
:::

This function fetches historical messages of a channel.

It is possible to control how messages are returned and in what order, for example you can:

* 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 time line 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 will receive messages that are **older** than and up to that `start` timetoken value. If only the `end` parameter is specified (without `start`), you will receive messages that match that `end` timetoken value and **newer**. Specifying values for both `start` *and* `end` parameters will return messages between those timetoken values (inclusive on the `end` value). Keep in mind that you will still receive a maximum of 100 messages even if there are more messages that meet the timetoken values. Iterative calls to history adjusting the `start` timetoken is necessary to page through the full set of results if more than 100 messages meet the timetoken values.
:::

### Method(s)

To run `History` you can use the following method(s) in the Python SDK:

```python
pubnub.history() \
    .channel(String) \
    .include_meta(True) \
    .reverse(Boolean) \
    .include_timetoken(Boolean) \
    .start(Integer) \
    .end(Integer) \
    .count(Integer)
```

| Parameter | Description |
| --- | --- |
| `channel` *Type: StringDefault: n/a | Specifies `channel` to return history messages from. |
| `include_meta`Type: BooleanDefault: `False` | Specifies whether or not the message's meta information should be returned. |
| `reverse`Type: BooleanDefault: `False` | Setting to `True` will traverse the time line in reverse starting with the oldest message first. |
| `include_timetoken`Type: BooleanDefault: `False` | Whether event dates timetokens should be included in response or not. |
| `start`Type: IntegerDefault: n/a | Timetoken delimiting the start of time slice (exclusive) to pull messages from. |
| `end`Type: IntegerDefault: n/a | Timetoken delimiting the end of time slice (inclusive) to pull messages from. |
| `count`Type: IntegerDefault: n/a | Specifies the number of historical messages to return. |

:::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:

```python
envelope = pubnub.history() \
    .channel("history_channel") \
    .count(100) \
    .sync()
```

### Returns

The `history()` operation returns a `PNHistoryResult` which contains the following fields:

| Method | Description |
| --- | --- |
| `messages`Type: List | List of messages of type `PNHistoryItemResult`. See [PNHistoryItemResult](#pnhistoryitemresult) for more details. |
| `start_timetoken`Type: Integer | Start `timetoken`. |
| `end_timetoken`Type: Integer | End `timetoken`. |

#### PNHistoryItemResult

| Method | Description |
| --- | --- |
| `timetoken`Type: Integer | `Timetoken` of the message. |
| `entry`Type: Object | Message. |

### Other examples

#### Use history() to retrieve the three oldest messages by retrieving from the time line in reverse

```python
envelope = pubnub.history() \
    .channel("my_channel") \
    .count(3) \
    .reverse(True) \
    .sync()
```

##### Response

```python
{
    end_timetoken: 13406746729185766,
    start_timetoken: 13406746780720711,
    messages: [{
        crypto: None,
        entry: 'Pub1',
        timetoken: None
    },{
        crypto: None,
        entry: 'Pub2',
        timetoken: None
    },{
        crypto: None,
        entry: 'Pub2',
        timetoken: None
    }]
}
```

#### Use history() to retrieve messages newer than a given timetoken by paging from oldest message to newest message starting at a single point in time (exclusive)

```python
pubnub.history()\
    .channel("my_channel")\
    .start(13847168620721752)\
    .reverse(True)\
    .sync()
```

##### Response

```python
{
    end_timetoken: 13406746729185766,
    start_timetoken: 13406746780720711,
    messages: [{
        crypto: None,
        entry: 'Pub4',
        timetoken: None
    },{
        crypto: None,
        entry: 'Pub5',
        timetoken: None
    },{
        crypto: None,
        entry: 'Pub6',
        timetoken: None
    }]
}
```

#### Use history() to retrieve messages until a given timetoken by paging from newest message to oldest message until a specific end point in time (inclusive)

```python
pubnub.history()\
    .channel("my_channel")\
    .count(100)\
    .start(-1)\
    .end(13847168819178600)\
    .reverse(True)\
    .sync()
```

##### Response

```python
{
    end_timetoken: 13406746729185766,
    start_timetoken: 13406746780720711,
    messages: [{
        crypto: None,
        entry: 'Pub4',
        timetoken: None
    },{
        crypto: None,
        entry: 'Pub5',
        timetoken: None
    },{
        crypto: None,
        entry: 'Pub6',
        timetoken: None
    }]
}
```

#### History paging example

:::note Usage
You can call the method by passing 0 or a valid **timetoken** as the argument.
:::

```python
def get_all_messages(start_tt):
    def history_callback(result, status):
        msgs = result.messages
        start = result.start_timetoken
        end = result.end_timetoken
        count = len(msgs)

        if count > 0:
            print("%d" % count)
            print("start %d" % start)
            print("end %d" % end)

        if count == 100:
            get_all_messages(start)

    pubnub.history()\
        .channel('history_channel')\
        .count(100)\
        .start(start_tt)\
        .pn_async(history_callback)

get_all_messages(14759343456292767)
```

#### Include timetoken in history response

```python
pubnub.history()\
    .channel("my_channel")\
    .count(100)\
    .include_timetoken()
    .sync()
```

## 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.