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

# Get user metadata

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

Returns metadata for the specified UUID, optionally including custom properties.

| Path Parameters |
| --- |
| `sub_key`string—**REQUIRED**Your app's subscribe key from Admin Portal. |
| `uuid`string—**REQUIRED**A UTF-8 encoded string used to identify the client. Must not be empty and can contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero. |

| Query Parameters |
| --- |
| `include`string[]Possible values: [custom, type, status]List of additional/complex UUID metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata. |
| `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. Authorization token with permissions to perform the request. |
| `signature`stringSignature used to verify that the request was signed with the secret key associated with the subscribe key.If Access Manager is enabled, either a valid authorization token or a signature are required. Check 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 seconds offset from NTP. Required if signature parameter is supplied. |

| Responses |
| --- |
| `200`Successfully retrieved the requested UUID metadata.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.data objectObject with UUID metadata used in responses.id string — OPTIONALPossible values: 1 ≤ length ≤ 92A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.updated date-timeDate and time the object was last updated.eTag stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs.name string — OPTIONALPossible values: 1 ≤ lengthName of the UUID. Max. 2,048 characters. Must not be empty or consist only of whitespace characters.externalId string — OPTIONALUUID's identifier in an external system. Max. 2,048 characters.profileUrl uri — OPTIONALURL for the UUID's profile picture. Max. 2,048 characters. Syntax is as defined in RFC 3986.email email — OPTIONALThe UUID's email address. Max. 320 characters. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed).type string — OPTIONALUser type. Max. 50 characters.status string — OPTIONALUser status. Max. 50 characters.custom object — OPTIONALJSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `data`objectObject with UUID metadata used in responses.id string — OPTIONALPossible values: 1 ≤ length ≤ 92A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.updated date-timeDate and time the object was last updated.eTag stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs.name string — OPTIONALPossible values: 1 ≤ lengthName of the UUID. Max. 2,048 characters. Must not be empty or consist only of whitespace characters.externalId string — OPTIONALUUID's identifier in an external system. Max. 2,048 characters.profileUrl uri — OPTIONALURL for the UUID's profile picture. Max. 2,048 characters. Syntax is as defined in RFC 3986.email email — OPTIONALThe UUID's email address. Max. 320 characters. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed).type string — OPTIONALUser type. Max. 50 characters.status string — OPTIONALUser status. Max. 50 characters.custom object — OPTIONALJSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. | `id`string—**OPTIONAL**Possible values: 1 ≤ length ≤ 92A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero. | `updated`date-timeDate and time the object was last updated. | `eTag`stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs. | `name`string—**OPTIONAL**Possible values: 1 ≤ lengthName of the UUID. Max. 2,048 characters. Must not be empty or consist only of whitespace characters. | `externalId`string—**OPTIONAL**UUID's identifier in an external system. Max. 2,048 characters. | `profileUrl`uri—**OPTIONAL**URL for the UUID's profile picture. Max. 2,048 characters. Syntax is as defined in RFC 3986. | `email`email—**OPTIONAL**The UUID's email address. Max. 320 characters. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed). | `type`string—**OPTIONAL**User type. Max. 50 characters. | `status`string—**OPTIONAL**User status. Max. 50 characters. | `custom`object—**OPTIONAL**JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `data`objectObject with UUID metadata used in responses.id string — OPTIONALPossible values: 1 ≤ length ≤ 92A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero.updated date-timeDate and time the object was last updated.eTag stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs.name string — OPTIONALPossible values: 1 ≤ lengthName of the UUID. Max. 2,048 characters. Must not be empty or consist only of whitespace characters.externalId string — OPTIONALUUID's identifier in an external system. Max. 2,048 characters.profileUrl uri — OPTIONALURL for the UUID's profile picture. Max. 2,048 characters. Syntax is as defined in RFC 3986.email email — OPTIONALThe UUID's email address. Max. 320 characters. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed).type string — OPTIONALUser type. Max. 50 characters.status string — OPTIONALUser status. Max. 50 characters.custom object — OPTIONALJSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. | `id`string—**OPTIONAL**Possible values: 1 ≤ length ≤ 92A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero. | `updated`date-timeDate and time the object was last updated. | `eTag`stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs. | `name`string—**OPTIONAL**Possible values: 1 ≤ lengthName of the UUID. Max. 2,048 characters. Must not be empty or consist only of whitespace characters. | `externalId`string—**OPTIONAL**UUID's identifier in an external system. Max. 2,048 characters. | `profileUrl`uri—**OPTIONAL**URL for the UUID's profile picture. Max. 2,048 characters. Syntax is as defined in RFC 3986. | `email`email—**OPTIONAL**The UUID's email address. Max. 320 characters. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed). | `type`string—**OPTIONAL**User type. Max. 50 characters. | `status`string—**OPTIONAL**User status. Max. 50 characters. | `custom`object—**OPTIONAL**JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. |
| `id`string—**OPTIONAL**Possible values: 1 ≤ length ≤ 92A UTF-8 encoded string used to identify the client. Must not be empty, and may contain up to 92 UTF-8 byte sequences.Prohibited characters are: ,, /, \, *, :, channel, non-printable ASCII control characters, and Unicode zero. |
| `updated`date-timeDate and time the object was last updated. |
| `eTag`stringInformation on the object's content fingerprint.NOTE: eTag from GET requests can be used alongside the If-Match HTTP header in conditional PATCH requests in users/channels' metadata APIs. This functionality is currently not supported in the membership/members' metadata APIs. |
| `name`string—**OPTIONAL**Possible values: 1 ≤ lengthName of the UUID. Max. 2,048 characters. Must not be empty or consist only of whitespace characters. |
| `externalId`string—**OPTIONAL**UUID's identifier in an external system. Max. 2,048 characters. |
| `profileUrl`uri—**OPTIONAL**URL for the UUID's profile picture. Max. 2,048 characters. Syntax is as defined in RFC 3986. |
| `email`email—**OPTIONAL**The UUID's email address. Max. 320 characters. Syntax is as defined by RFC 5322 and extended by RFC 6532, with one exception: the display-name part is not allowed (only the addr-spec part is allowed). |
| `type`string—**OPTIONAL**User type. Max. 50 characters. |
| `status`string—**OPTIONAL**User status. Max. 50 characters. |
| `custom`object—**OPTIONAL**JSON object of key/value pairs with supported data-types. Values must be scalar only; arrays or objects are not supported.NOTE: If you set custom fields with integer values, do not specify numbers larger than 9007199254740991 due to precision limitations in JSON implementations. For large integer values, for example PubNub timetoken values, use string values instead of integers. |
| `304`Requested resource has not been modified since the last retrieval. |
| `403`Disabled - The subscribe key doesn't have App Context API enabled.Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `404`The requested resource was not found.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `429`Request rate limit exceeded.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `500`An internal server error occurred.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `503`Request processing exceeded the maximum allowed time.Schema — OPTIONALstatus integer — OPTIONALHTTP status code.error object — OPTIONALError response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | Schema—**OPTIONAL** | `status`integer—**OPTIONAL**HTTP status code. | `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| Schema—**OPTIONAL** |
| `status`integer—**OPTIONAL**HTTP status code. |
| `error`object—**OPTIONAL**Error response.message string — OPTIONALUser-facing error message.source string — OPTIONALPossible values: [metadata, authz]Internal source of the error.details object[] — OPTIONALmessage string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**User-facing error message. | `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. | `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**User-facing error message. |
| `source`string—**OPTIONAL**Possible values: [metadata, authz]Internal source of the error. |
| `details`object[]—**OPTIONAL**message string — OPTIONALA user-facing error message.location string — OPTIONALName of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable.locationType string — OPTIONALPossible values: [path, query, header, body] | `message`string—**OPTIONAL**A user-facing error message. | `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. | `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |
| `message`string—**OPTIONAL**A user-facing error message. |
| `location`string—**OPTIONAL**Name of the offending query string parameter, or a dot-delimited JSON path to the source of the error in the input document, if applicable. |
| `locationType`string—**OPTIONAL**Possible values: [path, query, header, body] |

sub_key
*
Type:
string
Your app's subscribe key from
[Admin Portal](https://admin.pubnub.com)
.
uuid
*
Type:
string
A UTF-8 encoded string used to
[identify the client](https://www.pubnub.com/docs/architecture/core-concepts.md)
. Must not be empty and can contain up to 92 UTF-8 byte sequences.

Prohibited characters
are:
,
,
/
,
\
,
*
,
:
, channel, non-printable ASCII control characters, and Unicode zero.
include
Type:
array
List of additional/complex UUID metadata to include in the response. Omit this query parameter if you don't want to retrieve additional metadata.
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. Authorization token with permissions to perform the request.
signature
Type:
string
Signature used to verify that the request was signed with the secret key associated with the subscribe key.

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

Check
[Access Manager documentation](https://www.pubnub.com/docs/sdks/rest-api/access-manager-introduction.md)
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 seconds offset from NTP.

Required if
signature
parameter is supplied.
status
Type:
integer
HTTP status code.
data
Type:
object
Object with UUID metadata used in responses.
Example:
{"id":"uuid-1","name":"John Doe","externalId":null,"profileUrl":null,"email":"jack@twitter.com","updated":"2019-02-20T23:11:20.893Z","eTag":"MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="}
Example Response

```
{
  "status": 200,
  "data": {
    "id": "uuid-1",
    "name": "John Doe",
    "externalId": null,
    "profileUrl": null,
    "email": "jack@twitter.com",
    "updated": "2019-02-20T23:11:20.893Z",
    "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
  }
}
```

Disabled - The subscribe key doesn't have App Context API enabled.

Forbidden - The client isn't authorized to perform this operation. The authorization key you provided doesn't have the required permissions for this operation.
status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response
Example
1
Example
2

```
{
  "status": 403,
  "error": {
    "message": "Invalid signature",
    "source": "authz",
    "details": [
      {
        "message": "Client and server produced different signatures for the same inputs.",
        "location": "signature",
        "locationType": "query"
      }
    ]
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 404,
  "error": {
    "message": "Requested resource was not found.",
    "source": "metadata"
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 429,
  "error": {
    "message": "You have exceeded the maximum number of requests per second allowed for your subscribe key.",
    "source": "metadata"
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 500,
  "error": {
    "message": "An unexpected error occurred while processing the request.",
    "source": "metadata"
  }
}
```

status
Type:
integer
HTTP status code.
error
Type:
object
Error response.
Example Response

```
{
  "status": 503,
  "error": {
    "message": "The server took longer to respond than the maximum allowed processing time.",
    "source": "metadata"
  }
}
```