---
source_url: https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/history
title: Message history
updated_at: 2026-09-30T07:20:08.000Z
---

# Message history

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

PubNub APIs let you effectively fetch historical messages from direct, group, or public conversations.

While [App Context API](https://www.pubnub.com/docs/data-storage/metadata/overview.md) lets you manage metadata and relationships between users and channels, enabling efficient tracking of which channels are associated with a given user, [Message Persistence API](https://www.pubnub.com/docs/data-storage/message-history/overview.md) lets you retrieve messages from those channels. Together, these APIs enable you to gather all conversations involving a user and easily fetch specific message histories for any interactions between users.

Use `getHistory()` to fetch past messages from a channel.

:::note API limitation
Results cannot be filtered by message type. All messages within the specified timeframe are returned.
:::

##### Under the hood

`getHistory()` calls Message Persistence API and the JavaScript SDK [fetchMessages()](https://www.pubnub.com/docs/sdks/javascript/api-reference/storage-and-playback.md#fetch-history) method.

### Method signature

This method takes the following parameters:

```ts
channel.getHistory({
    startTimetoken?: string,
    endTimetoken?: string,
    count?: number
}): Promise<{
    messages: Message[],
    isMore: boolean
}>
```

#### Input

:::warning How to use the startTimetoken and endTimetoken parameters
PubNub retrieves messages by searching **backward through time** (newest to oldest). Because of this, the parameter names are the reverse of their intuitive meaning:
* **startTimetoken** is the **newer** boundary (higher timetoken value) - search begins here, **exclusive**
* **endTimetoken** is the **older** boundary (lower timetoken value) - search stops here, **inclusive**
When you provide both parameters, `startTimetoken` must be a **higher** timetoken than `endTimetoken`.
```mermaid
graph LR
    A(["9:00 AM<br/>(oldest)"]) -->|"time flows →"| B["endTimetoken = 10:00 AM<br/>older boundary<br/>inclusive ✓"]
    B --> C["retrieved<br/>messages"]
    C --> D["startTimetoken = 11:00 AM<br/>newer boundary<br/>exclusive ✗"]
    D -->|"time flows →"| E(["11:59 AM<br/>(newest)"])
    D -.->|"◄ API searches backward"| B
    style A fill:#f8f9fa,stroke:#6c757d,color:#495057
    style E fill:#f8f9fa,stroke:#6c757d,color:#495057
    style B fill:#d4edda,stroke:#28a745,color:#000
    style C fill:#cce5ff,stroke:#004085,color:#000
    style D fill:#fff3cd,stroke:#856404,color:#000
```
9:00 AM
10:00 AM
11:00 AM
11:59 AM
Results are always returned in oldest-first order.
:::

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| startTimetoken | string | Optional |  | [Timetoken](https://www.pubnub.com/docs/architecture/core-concepts.md#timetoken) delimiting the start of a time slice (exclusive) to pull messages from. For details, refer to the [Fetch History section](https://www.pubnub.com/docs/sdks/javascript/api-reference/storage-and-playback.md#fetch-history). |
| endTimetoken | string | Optional |  | Timetoken delimiting the end of a time slice (inclusive) to pull messages from. For details, refer to the [Fetch History section](https://www.pubnub.com/docs/sdks/javascript/api-reference/storage-and-playback.md#fetch-history). |
| count | number | Optional | `25` | Number of historical messages to return for the channel in a single call. Since each call returns all attached [message reactions](https://www.pubnub.com/docs/chat/chat-sdk/build/features/messages/reactions.md) by default, the maximum number of returned messages is `25`. For more details, refer to the description of the `includeMessageActions` parameter in the [JavaScript SDK docs](https://www.pubnub.com/docs/sdks/javascript/api-reference/storage-and-playback.md#methods). |

#### Output

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| Promise<> | object | Optional |  | Returned object containing two fields: `messages` and `isMore`. |
| > messages | Message[] | Optional |  | Array listing the requested number of historical [Message objects](https://www.pubnub.com/docs/chat/chat-sdk/learn/chat-entities/message.md). |
| > isMore | boolean | Optional |  | Whether there are any more historical messages to pull. |

By default, each call returns all message actions and metadata attached to the retrieved messages.

### Sample code

From the `support` channel, fetch `10` historical messages older than the timetoken `15343325214676133`.

```ts
// reference the "channel" object
const channel = await chat.getChannel("support")
// invoke the "getHistory()" method on the "channel" object
await channel.getHistory(
    {
        startTimetoken: "15343325214676133",
        count: 10
    }
)
```

Last updated at: 2026-09-30T07:20:08.000Z