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

# Dataset Metadata

> Fetch concordance-backed row counts, symbol counts, and date spans with liberator.metadata() (POST /liberator/metadata).

# Dataset metadata

Use `liberator.metadata()` to fetch **concordance-backed metrics** for one or more datasets — row counts, symbol counts, and start/end timestamps — without downloading source rows.

This is a Liberator **2.3+** API. It calls `POST /liberator/metadata` and is separate from `liberator.query()` / `liberator.get_dataframe()`. Do not pass `summary` or `symbol` to `query`; those parameters belong only on `metadata`.

<Note>
  The Python SDK helper ships with Liberator 2.3 client packages. Download the latest `liberator.py` from your Liberator Profile page if your client does not yet expose `liberator.metadata`.
</Note>

## Parameters

| Parameter | Description                                                                           | Type                                                      | Default                     |
| --------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------- |
| `name`    | Dataset name, or a list of dataset names                                              | String or list                                            | — (required)                |
| `summary` | Collapse the per-day dimension into a whole-history summary                           | Boolean                                                   | `false`                     |
| `symbol`  | Return per-symbol grain instead of per-dataset totals                                 | Boolean                                                   | `false`                     |
| `symbols` | Restrict metrics to this symbol or list of symbols (also used for entitlement checks) | String or list                                            | `null`                      |
| `back_to` | Beginning of the data-time window                                                     | Date string, microseconds UTC, or `null` (no lower bound) | `null`                      |
| `as_of`   | End of the data-time window                                                           | Date string, microseconds UTC, or `null` (now)            | `null`                      |
| `user`    | Your CloudQuant-assigned user identifier                                              | String                                                    | from `liberator.json` / env |
| `token`   | Your authentication token                                                             | String                                                    | from `liberator.json` / env |

## Grain matrix (`summary` × `symbol`)

| `summary` | `symbol` | Result grain              |
| --------- | -------- | ------------------------- |
| `false`   | `false`  | Per day, dataset totals   |
| `false`   | `true`   | Per day, per symbol       |
| `true`    | `false`  | Whole-dataset totals      |
| `true`    | `true`   | Whole-history, per symbol |

## Basic example

```python theme={null}
import liberator

liberator.url = "https://api.cloudquant.ai"

metrics = liberator.metadata(
    name="daily_bars",
    summary=False,
    symbol=False,
)

# list of metric dicts, for example:
# [{"dataset": "...", "date": "...", "symbol_count": ..., "row_count": ..., "start": ..., "end": ...}, ...]
print(metrics)
```

## Whole-dataset summary

```python theme={null}
metrics = liberator.metadata(
    name="daily_bars",
    summary=True,
    symbol=False,
)
```

## Per-symbol metrics

```python theme={null}
# Per day + per symbol
daily_by_symbol = liberator.metadata(
    name="daily_bars",
    summary=False,
    symbol=True,
    symbols=["AAPL", "MSFT"],
)

# Whole-history per symbol
history_by_symbol = liberator.metadata(
    name="daily_bars",
    summary=True,
    symbol=True,
    symbols=["AAPL"],
)
```

## Multiple datasets

```python theme={null}
metrics = liberator.metadata(
    name=["daily_bars", "minute_bars"],
    summary=True,
    symbol=False,
)
```

## Windowed metadata

```python theme={null}
metrics = liberator.metadata(
    name="daily_bars",
    summary=False,
    symbol=False,
    back_to="2025-01-01",
    as_of="2025-01-31",
)
```

## Return shape

`liberator.metadata()` returns a **list of metric dictionaries** (the `metrics` array from the streamed response). Typical fields include:

| Field           | Meaning                                         |
| --------------- | ----------------------------------------------- |
| `dataset`       | Dataset name                                    |
| `date`          | Calendar day (present when `summary=False`)     |
| `symbol`        | Symbol key (present when `symbol=True`)         |
| `symbol_count`  | Distinct symbols in the grain (when applicable) |
| `row_count`     | Row count for the grain                         |
| `start` / `end` | Timestamp bounds for the grain                  |

The HTTP response is streamed NDJSON (heartbeat frames, then a final `{"metrics": [...]}` object). The Python helper consumes heartbeats and returns only the metrics list.

## Related

* [Listing datasets](/api-reference/concepts/listing-datasets) — catalog, schema, and entitlement discovery via `liberator.datasets`
* [Query parameters](/api-reference/concepts/query-parameters) — row-level queries via `liberator.query` (not metadata)
* [Checking dataset access](/python-guide/dataset-access) — Python guide for exploring entitled datasets