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

# Get message history with actions

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

Show history messages within the given time range, along with their actions.

* The response is a list of messages, ordered by ascending `timetoken`, wherein some of the message objects may by augmented with actions.
* The actions for a given `message` are organized first by type, then by value. For a given (type, value) pair, all the unique UUIDs who posted that action will be shown, along with the `timetoken` when the post occurred. Pagination can be controlled with `start`, `end`, and `max` parameters, similar to the `get_actions_by_timetoken` operation.
* The server may truncate the number of messages in the response, due to internal limits on the number of queries which can be performed per request. However, the server will always give "complete" messages, in the sense that the messages returned here will always have all their actions. If truncation of the original query occurs, a `more` link will be provided. This indicates that internal limiting has occurred, and the more link itself can be used to continue fetching the originally requested range of messages.

Consider the scenario where most messages have relatively few actions (<`250`), but the first message has somehow accumulated 25000 actions. If the user requests `25` messages with actions, the first request to history with actions would return only the first message, with all of its 25000 actions underneath it, and provide a `more` link to signal that truncation has occurred. Then the next request would contain the other 24 messages along with all their actions.

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

| Query Parameters |
| --- |
| `start`numberNewer boundary of the time slice (exclusive). PubNub retrieves messages by searching backward through time (newest to oldest), so start must be a higher timetoken value than end when both are provided. If provided, retrieval begins at this timetoken and moves backward in time, excluding the message at this timetoken. If not provided, it defaults to the current time. To page through results, provide a start OR end timetoken. To retrieve a specific slice, provide both — start must be higher than end. For a full explanation with examples, see Message Persistence.Example: 123323123123123 |
| `end`numberOlder boundary of the time slice (inclusive). PubNub retrieves messages by searching backward through time (newest to oldest), so end must be a lower timetoken value than start when both are provided. If provided, retrieval stops at this timetoken and includes the message at this timetoken. To page through results, provide an end OR start timetoken. To retrieve a specific slice, provide both — end must be lower than start. For a full explanation with examples, see Message Persistence.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 |
| `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 / p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI |
| `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`OKSchema — OPTIONALstatus integer — OPTIONALerror boolean — OPTIONALerror_message string — OPTIONALchannels object — OPTIONALmore object — OPTIONALurl string — OPTIONALstart string — OPTIONALmax integer — OPTIONAL | Schema—**OPTIONAL** | `status`integer—**OPTIONAL** | `error`boolean—**OPTIONAL** | `error_message`string—**OPTIONAL** | `channels`object—**OPTIONAL** | `more`object—**OPTIONAL**url string — OPTIONALstart string — OPTIONALmax integer — OPTIONAL | `url`string—**OPTIONAL** | `start`string—**OPTIONAL** | `max`integer—**OPTIONAL** |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL** |
| `error`boolean—**OPTIONAL** |
| `error_message`string—**OPTIONAL** |
| `channels`object—**OPTIONAL** |
| `more`object—**OPTIONAL**url string — OPTIONALstart string — OPTIONALmax integer — OPTIONAL | `url`string—**OPTIONAL** | `start`string—**OPTIONAL** | `max`integer—**OPTIONAL** |
| `url`string—**OPTIONAL** |
| `start`string—**OPTIONAL** |
| `max`integer—**OPTIONAL** |
| `400`The request was invalid.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** |

sub_key
*
Type:
string
Your app's subscribe key from
[Admin Portal](https://admin.pubnub.com)
.
channel
*
Type:
string
The channel ID to perform the operation on.
start
Type:
number
Newer boundary of the time slice (exclusive). PubNub retrieves messages by searching backward through time (newest to oldest), so
start
must be a
higher
timetoken value than
end
when both are provided.

If provided, retrieval begins at this timetoken and moves backward in time, excluding the message at this timetoken. If not provided, it defaults to the current time. To page through results, provide a
start
OR
end
timetoken. To retrieve a specific slice, provide both —
start
must be higher than
end
.

For a full explanation with examples, see
[Message Persistence](https://www.pubnub.com/docs/data-storage/message-history/overview.md)
.
end
Type:
number
Older boundary of the time slice (inclusive). PubNub retrieves messages by searching backward through time (newest to oldest), so
end
must be a
lower
timetoken value than
start
when both are provided.

If provided, retrieval stops at this timetoken and includes the message at this timetoken. To page through results, provide an
end
OR
start
timetoken. To retrieve a specific slice, provide both —
end
must be lower than
start
.

For a full explanation with examples, see
[Message Persistence](https://www.pubnub.com/docs/data-storage/message-history/overview.md)
.
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.
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
Example:
200
error
Type:
boolean
Example:
false
error_message
Type:
string
channels
Type:
object
more
Type:
object
Example Response

```
{
  "status": 200,
  "error": false,
  "error_message": "",
  "channels": {
    "demo-channel": [
      {
        "message": "Hi",
        "timetoken": "15610547826970040",
        "uuid": "my-uuid",
        "message_type": 0,
        "meta": {
          "some-meta-key": "some_value"
        },
        "custom_message_type": "custom-user-msg-type",
        "actions": {
          "receipt": {
            "read": [
              {
                "uuid": "user-7",
                "actionTimetoken": "15610547826970044"
              }
            ]
          }
        }
      },
      {
        "message": "Hello",
        "timetoken": "15610547826970000",
        "uuid": "my-uuid",
        "message_type": 0,
        "meta": {
          "some-meta-key": "some_value"
        },
        "custom_message_type": "custom-user-msg-type",
        "actions": {
          "reaction": {
            "smiley_face": [
              {
                "uuid": "user-456",
                "actionTimetoken": "15610547826970050"
              }
            ],
            "raccoon": [
              {
                "uuid": "user-789",
                "actionTimetoken": "15610547826980050"
              },
              {
                "uuid": "user-567",
                "actionTimetoken": "15610547826970000"
              }
            ]
          }
        }
      }
    ]
  },
  "more": {
    "url": "/v3/history-with-actions/s/channel/c?start=15610547826970000&max=98",
    "start": "15610547826970000",
    "max": 98
  }
}
```

status
Type:
integer
Example:
400
error
Type:
boolean
Example:
true
error_message
Type:
string
Example:
"Invalid Arguments: start"
channels
Type:
object
Example:
{}