On this page

Just getting started? Check out our Getting Connected Guide to get your client setup. This document assumes that you've already followed our [installation guide](https://developers.ceramic.network/docs/protocol/ceramic-one/usage/installation).

Let's explore how to use Ceramic to read messages from a stream. Nodes in the Ceramic Network subscribe to data by expressing an [interest](https://developers.ceramic.network/docs/protocol/ceramic-one/concepts#interests) in a given data model. This interest is broadcast to the node's peers in the network, who will then initiate periodic synchronization of all data conforming to that model via [Recon](https://developers.ceramic.network/docs/protocol/ceramic-one/usage/consume#), a protocol tailor-made for the efficient synchronization of large sets of events.

## Consuming events

First, we'll learn how to register an interest. Then we'll learn how to read events matching our interests. Finally, we'll learn about some extra methods to fetch specific events from your ceramic-one node.

### `registerInterestModel`

This method allows end users to register interest in a specific data model within the Ceramic network. The model's identifier is, itself, the ID of a stream that defines its schema.

```typescript
import { CeramicClient, EventsFeedParams } from "@ceramic-sdk/http-client";

const ceramic = new CeramicClient({ url: "http://localhost:5101" });

// My model stream ID
const modelId = "kjzl6hvfrbw6c5i55ks5m4hhyuh0jylw4g7x0asndu97i7luts4dfzvm35oev65";

// Listen to all events written to instances of this model
await ceramic.registerInterestModel(modelId);
```

Upon success, the function won't return anything, but it will throw if there's an issue. You're now ready to read events from streams tied to this schema!

### `getEventsFeed`

This method allows users to poll for new events that match their interests. It follows a typical pagination screen, in which users may specify `limit`, the maximum number of results to return in a given query, and `resumeAt` an opaque token that the ceramic-one node can use to determine where the user left off in their last read.

### Prepare your request parameters

Let's assume I want to read 50 events matching my interests. Both of these parameters are optional, but we'll define them to illustrate their purpose. If no limit is defined, the SDK will retrieve all new events from the resume token.

```typescript
const params: EventsFeedParams = {
  limit: 50,
  resumeAt: "0", // The resumeToken returned from the last call to `getEventsFeed`
};
```

### Get a batch of events

```typescript
const events = await ceramic.getEventsFeed(params);
```

If there is an issue, `getEventsFeed` will throw. Otherwise, you'll get an object shaped like this:

```typescript
type EventsFeed = {
  events: {
    id: string;
    data?: string;
  }[];
  resumeToken: string;
};
```

### Getting individual events

Ceramic also offers a handful of simple APIs to fetch individual events from your ceramic-one node.

#### `getEvent`

This is the most straightforward of the event fetching methods. It returns an event of the form:

```typescript
type Event = {
  id: string;
  data?: string;
};
```

To fetch an event by its id, we use `getEvent`:

```typescript
const eventId = events.events[0].id; // The ID of the event we want to fetch
const event = await ceramic.getEvent(eventId);
```

There are also a small collection of simple helper functions to extract specific parts of an event.

#### `getEventData`

Extract the data payload from an event.

```typescript
const data = await ceramic.getEventData(eventId);
```

This is equivalent to:

```typescript
ceramic.getEvent(eventId).then((event) => event.data);
```

#### `getEventCAR`

Extract the data payload from an event and parse it as a CAR file.

```typescript
const data = await ceramic.getEventCAR(eventId);
```

`data` will be the parsed payload of the event.

#### `getEventType`

This method is useful for cases where you know the schema of the payload. To use it, you must have the [codeco](https://github.com/ceramicnetwork/codeco) package and your codec handy.

```bash
npm install --save codeco
```

Then, you can use it like this:

```typescript
import { Decoder } from "codeco";

type MyPayload = /* ... */;
const decoder: Decoder<unknown, MyPayload> = /* ... */;

const data: MyPayload = await ceramic.getEventType(decoder, eventId);
```