---
source_url: https://www.pubnub.com/docs/sdks/rest-api/get-message-history
title: Get message history
---

# Get message history

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

This function fetches historical messages from one or multiple channels. It's possible to control how messages are returned and in which time interval.

* if you specify only the `start` parameter (without `end`), you will receive messages that are older than the start timetoken
* if you specify only the `end` parameter (without `start`), you will receive messages from that end timetoken and newer
* if you specify values for both `start` and `end` parameters, you will retrieve messages between those timetokens (inclusive of the end value)

You will receive a maximum of 100 messages for a single channel or 25 messages for multiple channels (up to 500). If more messages meet the timetoken criteria, make iterative calls while adjusting the start timetoken to fetch the entire list of messages from Message Persistence.

| Path Parameters |
| --- |
| `sub_key`string—**REQUIRED**Your app's subscribe key from Admin Portal.Example: sub-c-50264475-1902-558x-d213-7p19052012n2 |
| `channels`string—**REQUIRED**The channel names to perform the operation on.Example: ch1,ch2 |

| Query Parameters |
| --- |
| `start`numberTimetoken delimiting the start of time slice (exclusive) to pull messages from. Exclusive means that the message associated with the timetoken will be excluded from the result.If provided, lets you select a start date, in Timetoken format. If not provided, it will default to current time. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. start is exclusive, that is, the first item returned will be the one immediately after the start Timetoken value.Example: 123323123123123 |
| `end`numberTimetoken delimiting the end of time slice (inclusive) to pull messages from. Inclusive means that the message associated with the timetoken will be included in the result.If provided, lets you select an end date, in Timetoken format. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. End is inclusive, that is, if a message is associated exactly with the end Timetoken, it will be included in the result.Example: 123323123123123 |
| `max`integerThe max number of messages to return. Default (and maximum value) is 100 messages where number of channels is 1, and 25 messages for any number of channels greater than one (or when retrieving message actions). The batch history is limited to 500 channels.Example: 25 |
| `include_meta`booleanSet to true to include metadata with returned messages. This metadata is set using the meta parameter with the publish operation. Default is false.Example: true |
| `include_uuid`booleanSet to true to include uuid with returned messages. This is set using the uuid parameter with the publish operation. Default is false.Example: true |
| `include_message_type`booleanSet to true to include pubnub message type with returned messages. Default is false.Example: true |
| `include_custom_message_type`booleanSet to true to include custom message type with returned messages. Default is false.Example: true |
| `encode_channels`booleanSet to true to encode the channel names int he response data. Default is true.Example: true |
| `auth`stringString which is either the auth key (Access Manager legacy) or a valid token (Access Manager) used to authorize the operation if access control is enabled.Example: authKey / p0thisAkFl043rhDdHRsCkNyZXisRBjoERtZXRhoENzaWdYIGOAeTyWGJI |
| `uuid`stringA UTF-8 encoded string of up to 92 characters used to identify the client.Example: myUniqueUserId |
| `signature`stringSignature used to verify that the request was signed with the secret key associated with the subscriber key.If Access Manager is enabled, either a valid authorization token or a signature are required.See Access Manager documentation for details on how to compute the signature. |
| `timestamp`integerUnix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.Required if signature parameter is supplied. |

| Responses |
| --- |
| `200`SuccessSchema — OPTIONALstatus integer — OPTIONALerror boolean — OPTIONALerror_message string — OPTIONALchannels object — OPTIONAL | Schema—**OPTIONAL** | `status`integer—**OPTIONAL** | `error`boolean—**OPTIONAL** | `error_message`string—**OPTIONAL** | `channels`object—**OPTIONAL** |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL** |
| `error`boolean—**OPTIONAL** |
| `error_message`string—**OPTIONAL** |
| `channels`object—**OPTIONAL** |
| `400`Invalid request.Schema — OPTIONALstatus integer — OPTIONALerror boolean — OPTIONALerror_message string — OPTIONALchannels object — OPTIONAL | Schema—**OPTIONAL** | `status`integer—**OPTIONAL** | `error`boolean—**OPTIONAL** | `error_message`string—**OPTIONAL** | `channels`object—**OPTIONAL** |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL** |
| `error`boolean—**OPTIONAL** |
| `error_message`string—**OPTIONAL** |
| `channels`object—**OPTIONAL** |
| `403`Do not have permissionSchema — OPTIONALstatus integer — OPTIONALerror boolean — OPTIONALerror_message string — OPTIONAL | Schema—**OPTIONAL** | `status`integer—**OPTIONAL** | `error`boolean—**OPTIONAL** | `error_message`string—**OPTIONAL** |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL** |
| `error`boolean—**OPTIONAL** |
| `error_message`string—**OPTIONAL** |

sub_key
*
Type:
string
Your app's subscribe key from
[Admin Portal](https://admin.pubnub.com)
.
channels
*
Type:
string
The channel names to perform the operation on.
start
Type:
number
Timetoken delimiting the start of time slice (exclusive) to pull messages from. Exclusive means that the message associated with the timetoken will be excluded from the result.

If provided, lets you select a
start
date, in Timetoken format. If not provided, it will default to current time. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. start is
exclusive
, that is, the first item returned will be the one immediately after the start Timetoken value.
end
Type:
number
Timetoken delimiting the end of time slice (inclusive) to pull messages from. Inclusive means that the message associated with the timetoken will be included in the result.

If provided, lets you select an
end
date, in Timetoken format. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. End is
inclusive
, that is, if a message is associated exactly with the end Timetoken, it will be included in the result.
max
Type:
integer
The max number of messages to return. Default (and maximum value) is 100 messages where number of channels is 1, and 25 messages for any number of channels greater than one (or when retrieving message actions). The batch history is limited to 500 channels.
include_meta
Type:
boolean
Set to true to include metadata with returned messages. This metadata is set using the meta parameter with the publish operation. Default is false.
include_uuid
Type:
boolean
Set to true to include uuid with returned messages. This is set using the uuid parameter with the publish operation. Default is false.
include_message_type
Type:
boolean
Set to true to include pubnub message type with returned messages. Default is false.
include_custom_message_type
Type:
boolean
Set to true to include custom message type with returned messages. Default is false.
encode_channels
Type:
boolean
Set to true to encode the channel names int he response data. Default is true.
auth
Type:
string
String which is either the auth key (Access Manager legacy) or a valid token (
[Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md)
) used to authorize the operation if access control is enabled.
uuid
Type:
string
A UTF-8 encoded string of up to 92 characters used to
[identify the client](https://www.pubnub.com/docs/architecture/core-concepts.md)
.
signature
Type:
string
Signature used to verify that the request was signed with the secret key associated with the subscriber key.

If Access Manager is enabled, either a valid authorization token or a signature are required.

See Access Manager documentation for details on how to compute the signature.
timestamp
Type:
integer
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.

Required if
signature
parameter is supplied.
status
Type:
integer
error
Type:
boolean
error_message
Type:
string
channels
Type:
object
Example Response

```
{
  "status": 200,
  "error": false,
  "error_message": "",
  "channels": {
    "demo-channel": [
      {
        "message": "Hello world",
        "timetoken": "15610547826970040",
        "uuid": "my-uuid",
        "message_type": 0,
        "meta": {
          "some-meta-key": "some_value"
        },
        "custom_message_type": "custom-user-msg-type"
      }
    ]
  }
}
```

status
Type:
integer
Example:
400
error
Type:
boolean
Example:
true
error_message
Type:
string
Example:
"Invalid Arguments: start"
channels
Type:
object
Example:
{}
status
Type:
integer
Example:
403
error
Type:
boolean
Example:
true
error_message
Type:
string
Example:
"Do not have permission to delete"