# rpk topic consume

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt)

---
title: rpk topic consume
latest-redpanda-tag: v26.1.14
latest-console-tag: v3.10.0
latest-operator-version: v26.2.2
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "false"
page-is-past-eol: "false"
page-eol-date: March 31, 2027
latest-connect-version: 4.105.0
docname: rpk/rpk-topic/rpk-topic-consume
page-component-name: streaming
page-version: "26.1"
page-component-version: "26.1"
page-component-title: Streaming
page-relative-src-path: rpk/rpk-topic/rpk-topic-consume.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/v/26.1/modules/reference/pages/rpk/rpk-topic/rpk-topic-consume.adoc
description: Consume records from topics. Consuming records reads from any amount of input topics, formats each record according to <code>--format</code>, and prints them to <code>STDOUT</code>.
page-git-created-date: "2023-05-17"
page-git-modified-date: "2026-07-17"
support-status: supported
---

<!-- Source: https://docs.redpanda.com/streaming/26.1/reference/rpk/rpk-topic/rpk-topic-consume.md -->

Consume records from topics. Consuming records reads from any amount of input topics, formats each record according to `--format`, and prints them to `STDOUT`.

The output formatter understands a wide variety of formats. The default output format `--format json` is a special format that outputs each record as JSON.

## [](#formatting)Formatting

Formatting is based on percent escapes and modifiers. Slashes can be used for common escapes:

| Escape | Description |
| --- | --- |
| \t | Tabs |
| \n | Newlines |
| \r | Carriage returns |
| \\ | Slashes |
| \xNN | Hex encoded characters |

The percent encodings are represented like this:

| Percent encoding | Description |
| --- | --- |
| %t | Topic |
| %T | Topic length |
| %k | Key |
| %K | Key length |
| %v | Value |
| %V | Value length |
| %h | Begin the header specification |
| %H | Number of headers |
| %p | Partition |
| %o | Offset |
| %e | Leader epoch |
| %d | Timestamp (formatting described below) |
| %x | Producer ID |
| %y | Producer epoch |
| %[ | Partition log start offset |
| %| | Partition last stable offset |
| %] | Partition high watermark |
| %% | Record attributes (formatting described below) |
| %a | Percent sign |
| %{ | Left brace |
| %} | Right brace |
| %i | Number of records formatted |

### [](#modifiers)Modifiers

Text and numbers can be formatted in many different ways, and the default format can be changed within brace modifiers. `%v` prints a value, while `%v{hex}` prints the value hex encoded. `%T` prints the length of a topic in ASCII, while `%T{big8}` prints the length of the topic as an eight byte big endian.

All modifiers go within braces following a percent-escape.

### [](#numbers)Numbers

Formatting number values can have the following modifiers:

| Format | Description |
| --- | --- |
| ascii | Print the number as ASCII (default) |
| hex64 | Sixteen hex characters |
| hex32 | Eight hex characters |
| hex16 | Four hex characters |
| hex8 | Two hex characters |
| hex4 | One hex character |
| big64 | Eight byte big endian number |
| big32 | Four byte big endian number |
| big16 | Two byte big endian number |
| big8 | Alias for byte |
| little64 | Eight byte little endian number |
| little32 | Four byte little endian number |
| little16 | Two byte little endian number |
| little8 | Alias for byte |
| byte | One byte number |
| bool | true if the number is non-zero, false if the number is zero |

All numbers are truncated as necessary per the modifier. Printing `%V{byte}` for a length 256 value prints a single null, whereas printing `%V{big8}` prints the bytes 1 and 0.

When writing number sizes, the size corresponds to the size of the raw values, not the size of encoded values. `%T% t{hex}` for the topic `foo` prints `3 666f6f`, not `6 666f6f`.

### [](#timestamps)Timestamps

By default, the timestamp field is printed as a millisecond number value. In addition to the number modifiers above, timestamps can be printed with either `Go` formatting:

```go
%d{go[2006-01-02T15:04:05Z07:00]}
```

Or `strftime` formatting:

```go
%d{strftime[%F]}
```

An arbitrary amount of brackets (or braces, or # symbols) can wrap your date formatting:

```go
%d{strftime=== [%F] ===}
```

This prints `[YYYY-MM-DD]`, while the surrounding three # on each side are used to wrap the formatting.

For more information on Go time formatting, see the [Go documentation](https://pkg.go.dev/time).

For more information on `strftime` formatting, run `man strftime`.

## [](#usage)Usage

```bash
rpk topic consume TOPICS... [flags]
```

### [](#attributes)Attributes

Each record (or batch of records) has a set of possible attributes. Internally, these are packed into bit flags. Printing an attribute requires first selecting which attribute you want to print, and then optionally specifying how you want it to be printed:

```bash
%a{compression}
%a{compression;number}
%a{compression;big64}
%a{compression;hex8}
```

Compression is by default printed as text (`none`, `gzip`, …​). Compression can be printed as a number with `;number`, where number is any number formatting option described above. No compression is `0`, gzip is `1`, etc.

```bash
%a{timestamp-type}
%a{timestamp-type;big64}
```

The record’s timestamp type prints as:

-   `-1` for very old records (before timestamps existed)

-   `0` for client-generated timestamps

-   `1` for broker-generated timestamps


> 📝 **NOTE**
>
> Number formatting can be controlled with `;number`.

```bash
%a{transactional-bit}
%a{transactional-bit;bool}
```

Prints `1` if the record is a part of a transaction or `0` if it is not.

```bash
%a{control-bit}
%a{control-bit;bool}
```

Prints `1` if the record is a commit marker or `0` if it is not.

### [](#text)Text

Text fields without modifiers default to writing the raw bytes. Alternatively, there are the following modifiers:

| Modifier | Description |
| --- | --- |
| %t{hex} | Hex encoding |
| %k{base64} | Base64 standard encoding |
| %k{base64raw} | Base64 encoding raw |
| %v{unpack[<bBhH>iIqQc.$]} | The unpack modifier has a further internal specification, similar to timestamps above. |

Unpacking text can allow translating binary input into readable output. If a value is a big-endian uint32, `%v` prints the raw four bytes, while `%v{unpack[>I]}` prints the number as ASCII. If unpacking exhausts the input before something is unpacked fully, an error message is appended to the output.

### [](#headers)Headers

Headers are formatted with percent encoding inside of the modifier:

```bash
%h{%k=%v{hex}}
```

This prints all headers with a space before the key and after the value, an equals sign between the key and value, and with the value hex encoded. Header formatting actually just parses the internal format as a record format, so all of the above rules about `%K`, `%V`, text, and numbers apply.

### [](#values)Values

Values for consumed records can be omitted by using the `--meta-only` flag.

Tombstone records (records with a `null` value) have their value omitted from the JSON output by default. All other records, including those with an empty-string value (`""`), have their values printed.

### [](#offsets)Offsets

The `--offset` flag allows for specifying where to begin consuming, and optionally, where to stop consuming. The literal words `start` and `end` specify consuming from the start and the end.

| Offset | Description |
| --- | --- |
| start | Consume from the beginning |
| end | Consume from the end |
| :end | Consume until the current end |
| +oo | Consume oo after the current start offset |
| -oo | Consume oo before the current end offset |
| oo | Consume after an exact offset |
| oo: | Alias for oo |
| :oo | Consume until an exact offset |
| o1:o2 | Consume from exact offset o1 until exact offset o2 |
| @t | Consume starting from a given timestamp |
| @t: | Alias for @t |
| @:t | Consume until a given timestamp |
| @t1:t2 | Consume from timestamp t1 until timestamp t2 |

Each timestamp option is evaluated until one succeeds.

| Timestamp | Description |
| --- | --- |
| 13 digits | Parsed as a unix millisecond |
| 9 digits | Parsed as a unix second |
| YYYY-MM-DD | Parsed as a day, UTC |
| YYYY-MM-DDTHH:MM:SSZ | Parsed as RFC3339, UTC; fractional seconds optional (.MMM) |
| -dur | Duration; from now (as t1) or from t1 (as t2) |
| dur | For t2 in @t1:t2, relative duration from t1 |
| end | For t2 in @t1:t2, the current end of the partition |

Durations are parsed simply:

```bash
3ms    three milliseconds
10s    ten seconds
9m     nine minutes
1h     one hour
1m3ms  one minute and three milliseconds
```

## [](#examples)Examples

This section provides examples of how to use `rpk topic consume`.

### [](#format-examples)Format examples

A key and value, separated by a space and ending in newline

```bash
rpk topic consume my-topic -f '%k %v\n'
```

A key length as four big endian bytes and the key as hex

```bash
rpk topic consume my-topic -f '%K{big32}%k{hex}'
```

A little endian uint32 and a string unpacked from a value

```bash
rpk topic consume my-topic -f '%v{unpack[is$]}'
```

### [](#offset-examples)Offset examples

Consume 1 hour of data on Valentine’s Day 2022

```bash
rpk topic consume my-topic -o @2022-02-14:1h
```

Consume from 2 days ago to 1 day ago

```bash
rpk topic consume my-topic -o @-48h:-24h
```

Consume from 1 minute ago until now

```bash
rpk topic consume my-topic -o @-1m:end
```

Consume from the start until an hour ago

```bash
rpk topic consume my-topic -o @:-1hr
```

## [](#flags)Flags

| Value | Type | Description |
| --- | --- | --- |
| -b, --balancer | string | Group balancer to use when consuming with a consumer group (range, roundrobin, sticky, cooperative-sticky). |
| --fetch-max-bytes | int32 | Maximum number of bytes per fetch request per broker. |
| --fetch-max-partition-bytes | int32 | Maximum number of bytes to fetch for a single partition per fetch request. |
| --fetch-max-wait | duration | Maximum amount of time to wait when fetching from a broker before the broker replies. |
| -f, --format | string | Output format (see --help for details). |
| -g, --group | string | Group to use for consuming (incompatible with -p). |
| --meta-only | bool | Print all record info except the record value (for -f json). |
| -n, --num | int | Quit after consuming this number of records (0 is unbounded). |
| -o, --offset | string | Offset to consume from / to (start, end, 47, +2, -3). |
| -p, --partitions | int32Slice | Comma delimited list of specific partitions to consume. |
| --pretty-print | bool | Pretty print each record over multiple lines (for -f json). |
| --print-control-records | bool | Opt in to printing control records. |
| --rack | string | Rack to use for consuming, which opts into follower fetching. |
| --read-committed | bool | Opt in to reading only committed offsets. |
| -r, --regex | bool | Parse topics as regex; consume any topic that matches any expression. |
| --use-schema-registry | stringSlice | Decode record keys and values using schemas from the schema registry. Use =key or =value to decode only the key or value. |

## [](#global-flags)Global flags

| Value | Type | Description |
| --- | --- | --- |
| --config | string | Redpanda or rpk config file; default search paths are ~/.config/rpk/rpk.yaml, $PWD/redpanda.yaml, and /etc/redpanda/redpanda.yaml. |
| -X, --config-opt | stringArray | Override rpk configuration settings; -X help for detail or -X list for terser detail. |
| --ignore-profile | bool | Ignore rpk.yaml and redpanda.yaml; use default settings. |
| --profile | string | rpk profile to use. |
| -v, --verbose | bool | Enable verbose logging. |