# List hub dataset refs

Source: https://stratadb.org/docs/reference/hub/list_refs

List live refs for a StrataHub dataset.

| | |
|---|---|
| Command | `hub.list_refs` |
| CLI | `strata hub list-refs` |
| Wire type | `hub_list_refs` |
| Python | `db.hub.list_refs(dataset: 'str', *, hub_url: 'Optional[str]' = None) -> 'Any'` |
| Access | read |
| Commit | no commit |
| Wire status | stable |

Reads `GET /v1/datasets/<name>/refs` from the effective hub URL. Yanked refs are filtered by the hub.

Status commands return a scalar or compact status payload and do not mutate database state.

## Examples

### Python

```python
[ref.branch for ref in db.hub.list_refs("titanic").refs]   # doctest: +SKIP
```

## Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `dataset` | `string` | yes | Dataset slug. |
| `hub_url` | `string or null` | no | Explicit hub URL; when absent the 5-layer resolver runs. |

## Returns

`StatusResponse<HubRefList>`

- `data` (`HubRefList`)
- `type` (`string`)

## Errors

Recover by code, never by message.

| Code | Retry | Commit outcome |
|---|---|---|
| [`failed_precondition.engine.runtime_closed`](https://stratadb.org/e/failed_precondition.engine.runtime_closed) | never | not_started |
| [`not_found.engine.branch`](https://stratadb.org/e/not_found.engine.branch) | never | not_applicable |
| [`unsupported.executor.hub_feature_disabled`](https://stratadb.org/e/unsupported.executor.hub_feature_disabled) | after_state_change | not_started |
| [`invalid_argument.executor.hub_url`](https://stratadb.org/e/invalid_argument.executor.hub_url) | never | not_started |
| [`unavailable.executor.hub_transport`](https://stratadb.org/e/unavailable.executor.hub_transport) | same_request | not_started |
| [`invalid_argument.executor.hub_dataset`](https://stratadb.org/e/invalid_argument.executor.hub_dataset) | never | not_started |
| [`not_found.executor.hub_dataset`](https://stratadb.org/e/not_found.executor.hub_dataset) | never | not_started |

## Related

- [Read hub dataset](https://stratadb.org/docs/reference/hub/get_dataset)
- [Read hub info](https://stratadb.org/docs/reference/hub/info)
- [List hub datasets](https://stratadb.org/docs/reference/hub/list_datasets)
- [List yanked hub refs](https://stratadb.org/docs/reference/hub/list_yanked)