# Displays (/api/displays)



`inklet.displays` is read-only. Displays are bound to your account through the
Portal or the mobile app; the SDK observes them.

## `list()` [#list]

```ts
const page = await inklet.displays.list({ limit: 20 });
```

```ts
list(options?: ListDisplaysOptions): Promise<DisplayPage>
```

<SdkType file="displays" name="ListDisplaysOptions" />

Returns a cursor page:

<SdkType file="displays" name="DisplayPage" />

Paging through everything:

```ts
let cursor: string | undefined;
const all = [];

do {
  const page = await inklet.displays.list({ cursor, limit: 50 });
  all.push(...page.items);
  cursor = page.nextCursor ?? undefined;
} while (cursor);
```

A `limit` outside 1–50, or a non-integer, throws `ConfigurationError` locally.

## `retrieve()` [#retrieve]

```ts
const display = await inklet.displays.retrieve("display_123");
```

Throws `NotFoundError` if the id is unknown, and `ConfigurationError` if the id
is not a non-empty string.

## `listQueue()` [#listqueue]

What is waiting for a display, optionally within a time range:

```ts
const queue = await inklet.displays.listQueue(display.id, {
  from: new Date("2026-08-01T00:00:00Z"),
  to: new Date(),
  limit: 20,
});
```

```ts
listQueue(displayId: string, options?: ListDisplayQueueOptions): Promise<DisplayQueuePage>
```

<SdkType file="displays" name="ListDisplayQueueOptions" />

`from` and `to` accept a `Date` or anything `new Date()` parses; both are sent
as ISO strings. An unparseable value, or `to` earlier than `from`, throws
`ConfigurationError`.

Each item:

<SdkType file="displays" name="DisplayQueueItem" />

## `current()` [#current]

The confirmed Presentation a display is showing, or `null`:

```ts
const current = await inklet.displays.current(display.id, { format: "png" });

if (current?.image) {
  console.log(current.image.url);
} else {
  console.log("nothing confirmed yet");
}
```

```ts
current(displayId: string, options?: { format?: "png" | "raw2" | "raw4" }): Promise<Presentation | null>
```

<Callout>
  `null` is a normal answer, not an error — a display that has never confirmed
  a frame has no current Presentation. Handle it before reading `.image`.
</Callout>

## The `Display` type [#the-display-type]

<SdkType file="displays" name="Display" />

| Field                   | Notes                                                                      |
| ----------------------- | -------------------------------------------------------------------------- |
| `name` / `nickname`     | `name` is the bound device name; `nickname` is user-set and may be `null`. |
| `tags`                  | Free-form labels — a practical routing key for Manual pushes.              |
| `online`                | Whether the panel is currently reachable.                                  |
| `syncIntervalMinutes`   | How often it wakes to ask for work.                                        |
| `nextSyncAt`            | When to expect the next pickup.                                            |
| `pendingPresentationId` | Handed over but not yet confirmed.                                         |

### Capabilities [#capabilities]

<SdkType file="displays" name="DisplayCapabilities" />

Read these before sending format-sensitive content — particularly for
[Hardcode pushes](/push/hardcode), where you control the pixels.