---
title: "Enable message consumption from a specific stream layer."
method: POST
path: "/layers/{layerId}/subscribe"
tags: ["stream"]
---

# Enable message consumption from a specific stream layer.

`POST /layers/{layerId}/subscribe`

Enables message consumption from a specific stream layer (topic). Use the base path returned from the API Lookup service.
Note: For **mode = parallel**, one unit of parallelism currently equals 1 MBps inbound or 2 MBps outbound, whichever is greater, rounded up to the nearest integer. The number of subscriptions within the same group cannot exceed the parallelism allowed. For more details see [Get Data from a Stream Layer](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/getting-data-stream.html).

## Path parameters

- `layerId` string, required

## Query parameters

- `mode` 'serial' | 'parallel'
- `subscriptionId` string
- `consumerId` string

## Request body

- SubscriptionProperties
  - `kafkaConsumerProperties` KafkaConsumerProperties — This is the same as [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs) with some default values changed.
    - `auto.commit.interval.ms` integer — Refer to [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs)
    - `auto.offset.reset` 'latest' | 'earliest' | 'none' — Refer to [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs)
    - `enable.auto.commit` boolean — Refer to [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs)
    - `fetch.max.bytes` integer — Refer to [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs)
    - `fetch.max.wait.ms` integer — Refer to [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs)
    - `fetch.min.bytes` integer — Refer to [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs)
    - `group.id` string — For applications intending to read in parallel mode belonging to same 'group.id' the values for 'catalogId, layerId, aid' should also be same
    - `max.partition.fetch.bytes` integer — Refer to [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs)
    - `max.poll.records` integer — Refer to [Kafka Consumer properties](https://kafka.apache.org/11/documentation.html#newconsumerconfigs)

## Response `201`

OK

- ConsumerSubscribeResponse
  - `nodeBaseURL` string — A subscription/Kafka Consumer is created in a specific server instance. This base URL represents the specific server node on which this subscription/Kafka Consumer was created. This base URL should be used instead of the base URL returned by the `lookup` service when making requests to these endpoints: /partitions, /offsets, /seek and /subscribe (DELETE).
  - `subscriptionId` string

## Other responses

- `400` — Bad Request
- `401` — Unauthorized - the request didn't provide correct authentication details
- `403` — Forbidden - the specific account doesn't have correct privileges to perform the operation
- `404` — Not found
- `412` — Pre-condition failed
- `500` — Internal Server Error
- `503` — Service Unavailable error

---

[API](https://skmtc.dev/here/apis/query-api-v1.md) · [All operations](https://skmtc.dev/here/apis/query-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/here/query-api-v1/revisions/30e5d2645407/schema)