Method: messages.list

Full name: projects.locations.datasets.hl7V2Stores.messages.list

Lists all the messages in the given HL7v2 store with support for filtering.

Note: HL7v2 messages are indexed asynchronously, so there might be a slight delay between the time a message is created and when it can be found through a filter.

HTTP request


The URL uses gRPC Transcoding syntax.

Path parameters



Name of the HL7v2 store to retrieve messages from.

Authorization requires the following IAM permission on the specified resource parent:

  • healthcare.hl7V2Messages.list

Query parameters



Limit on the number of messages to return in a single response. If zero the default page size of 100 is used.



The nextPageToken value returned from the previous List request, if any.



Restricts messages returned to those matching a filter. Syntax:

Fields/functions available for filtering are:

  • messageType, from the MSH-9.1 field. For example, NOT messageType = "ADT".
  • send_date or sendDate, the YYYY-MM-DD date the message was sent in the dataset's timeZone, from the MSH-7 segment. For example, send_date < "2017-01-02".
  • sendTime, the timestamp when the message was sent, using the RFC3339 time format for comparisons, from the MSH-7 segment. For example, sendTime < "2017-01-02T00:00:00-05:00".
  • sendFacility, the care center that the message came from, from the MSH-4 segment. For example, sendFacility = "ABC".
  • PatientId(value, type), which matches if the message lists a patient having an ID of the given value and type in the PID-2, PID-3, or PID-4 segments. For example, PatientId("123456", "MRN").
  • labels.x, a string value of the label with key x as set using the Message.labels map. For example, labels."priority"="high". The operator :* can be used to assert the existence of a label. For example, labels."priority":*.


Orders messages returned by the specified orderBy clause. Syntax:

Fields available for ordering are:

  • sendTime


Specifies the parts of the Message to return in the response. When unspecified, equivalent to BASIC. Setting this to anything other than BASIC with a pageSize larger than the default can generate a large response, which impacts the performance of this method.

Request body

The request body must be empty.

Response body

If successful, the response body contains data with the following structure:

Lists the messages in the specified HL7v2 store.

JSON representation
  "hl7V2Messages": [
  "nextPageToken": string


The returned Messages. Won't be more Messages than the value of pageSize in the request. See view for populated fields.



Token to retrieve the next page of results or empty if there are no more results in the list.

Authorization Scopes

Requires one of the following OAuth scopes:


For more information, see the Authentication Overview.