# Offsets

**Kind:** Interface

**Source:** [`packages/microservices/external/kafka.interface.ts`](https://github.com/nestjs/nest/blob/master/packages/microservices/external/kafka.interface.ts#L781)

**Part of:** [Microservices](subsystem-packages-microservices)

`Offsets` represents a collection of Kafka topic offset definitions. It is used when working with consumer position management, allowing callers to provide offset information for one or more topics through the `topics` array.

## Properties

| Property | Type |
|---|---|
| `topics` | `TopicOffsets[]` |

## Diagram

```mermaid
graph LR
  Offsets[Offsets] --> Topics[topics: TopicOffsets[]]
  Topics --> TopicOffset1[TopicOffsets]
  Topics --> TopicOffset2[TopicOffsets]
  TopicOffset1 --> Kafka[Kafka topic/partition offsets]
  TopicOffset2 --> Kafka
```

## Usage

```ts
import { Offsets, TopicOffsets } from './kafka.interface';

const topicOffsets: TopicOffsets[] = [
  {
    topic: 'orders',
    partitions: [
      { partition: 0, offset: '125' },
      { partition: 1, offset: '98' },
    ],
  },
];

const offsets: Offsets = {
  topics: topicOffsets,
};

// Pass offsets to the Kafka client operation that accepts topic offsets.
await kafkaConsumer.seek(offsets);
```

## AI Coding Instructions

- Populate `topics` with valid `TopicOffsets` objects; do not pass raw topic names or partition offsets directly.
- Preserve Kafka offsets as strings when the underlying client API expects string-based offsets.
- Include all relevant partitions when resetting or seeking consumer positions for a topic.
- Validate topic names and partition numbers against the Kafka cluster metadata before applying offsets.
- Use this interface with Kafka consumer offset-management operations such as seeking, committing, or resetting positions.