> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# blobhub workflow listeners

> Show a session's listeners with their switch, slots and outcomes, or one listener in detail

`listeners` reads the [listeners](https://docs.blobhub.io/blob-types/workflow/workflows/listeners.md) of a session: every declared listener of
the revision with its switch, its slots, its pending batch and what it last did, then the connection listeners that
are open on the session. With `--listener` it shows one declared listener in full, with the runs it started.

It only reads. To turn a listener on or off, use [`listener enable|disable`](https://docs.blobhub.io/cli/workflow/commands/listener).

## Synopsis

```bash theme={null}
blobhub workflow listeners <session> [--file <manifest>] [--listener <alias-or-id>]
```

| Flag | Default | Description |
| - | - | - |
| `<session>` | required | A session, or `<blob-id>/<revision>/<session>`, or `<org>/<blob>/<revision>/<session>`. The three shapes are those of [`events`](https://docs.blobhub.io/cli/workflow/commands/events#the-session-argument). |
| `--file`, `-f` | none | Manifest naming the blob and revision of a bare session. Refused beside a qualified one. |
| `--listener` | none | Show one declared listener: its alias or id. |

## The listing

One row per declared listener, in the order the platform returns them:

```text theme={null}
ALIAS       ENABLED       MODE      RETRY   SLOTS  PENDING  LAST                                     COUNTS
orchestrate on            serial    2x30s   1/1    0        success 1794243847100000                 refused=1 success=14
digest      off (session) parallel  -       0/4    0        -                                        -
```

| Column | Reads |
| - | - |
| `ALIAS` | The listener definition's alias. |
| `ENABLED` | `on` or `off`, the effective switch; `(session)` when this session overrides the definition's own. |
| `MODE` | The concurrency mode: `serial`, `keyed` or `parallel`. |
| `RETRY` | The listener's `retry` as `<attempts>x<delay>s`, such as `2x30s`, with the default delay of 30 seconds filled in when the body names none; `-` when it has no `retry`. |
| `SLOTS` | Runs in flight over the cap: 1 for `serial`, `max_parallel` otherwise. |
| `PENDING` | Events collected for the next batch. |
| `LAST` | The status and time of the latest outcome (`at`, in epoch microseconds), or `-`. |
| `COUNTS` | Outcomes by status, such as `success=14`. |

Connection listeners follow under their own heading, with their listener id, connection id, creation time and filter.
A connection listener has no switch and writes no outcome.

## One listener

`--listener <alias-or-id>` prints the listener's `filter`, `batch`, `concurrency`, `retry` and target, its newest 20
outcomes, and the first page of the executions it started. A line appears only for a field the body has; a stored body
always has `concurrency` and its target. An outcome ends with `retry=<n>` only when it is a retry's own: `1` on a
batch's first retry, `2` on its second, and nothing on its first delivery:

```text theme={null}
orchestrate  on  slots 1/1  refused=1 success=14
description: Drive each cell's procedure
filter: {"types": ["thread.item_posted"], "aliases": ["missions/**"]}
batch: {"window_seconds": 2, "max_events": 100}
concurrency: {"mode": "serial"}
retry: {"attempts": 2, "delay_seconds": 30}
invocation_target_type: "workflow"
invocation_target: {"workflow": {"definition": "orchestrator"}}

Outcomes
  1794243847100000  success  count=3  batch=...  retry=1

Runs
  5f2c0a91-...  completed
  more exist after 5f2c0a91-...
```

The runs page examines at most 1,000 executions. When it is full, the last line is `more exist after <id>`. When it
holds none but more exist, the command says
`no runs in the newest 1,000 executions; more exist`. A name that is not a declared listener of the revision is
`LISTENER_NOT_FOUND`.

Under `--json` the payload is `{session_id, listeners, connections}`, or with `--listener`
`{session_id, listener, executions, last_execution_id}`, each entry as the platform returns it, alongside the
envelope's `schema_version`.

## Errors

| Code | When |
| - | - |
| `SESSION_REFERENCE_INVALID` | `<session>` is malformed, bare without `-f`, or qualified beside `-f`. |
| `SESSION_NOT_ACCESSIBLE` | The session is absent or not reachable with this key. |
| `LISTENER_NOT_FOUND` | `--listener` names no declared listener of the revision. |
| `MANIFEST_NOT_FOUND`, `MANIFEST_INVALID`, `MANIFEST_TYPE_MISMATCH`, `MANIFEST_VERSION_UNSUPPORTED` | The manifest given with a bare session is absent or unusable. |
| `BLOB_NOT_ACCESSIBLE`, `BLOB_NOT_WORKFLOW`, `REVISION_NOT_ACCESSIBLE`, `REVISION_NOT_WRITABLE` | The blob or revision cannot be resolved, or its status is not `ready`. |
| `CREDENTIALS_NOT_FOUND`, `PROFILE_NOT_FOUND`, `INSECURE_CREDENTIALS_PERMISSIONS` | No usable credential, or a credentials file the CLI refuses to read. |

Every code above, with its remediation, is in [Error codes](https://docs.blobhub.io/cli/error-codes.md).

## See also

* [Listeners](https://docs.blobhub.io/blob-types/workflow/workflows/listeners.md) — bindings, the body, outcomes and the switch.
* [`blobhub workflow listener enable|disable`](https://docs.blobhub.io/cli/workflow/commands/listener) — flip a listener for one session.
* [`blobhub workflow events`](https://docs.blobhub.io/cli/workflow/commands/events) — `--listener` lists the events a listener caused.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.