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

# Dashboard Query

> Python API reference for Netra Dashboard queries. Fetch metrics, session summaries, and usage data programmatically with the dashboard query API.

The Netra SDK exposes a `dashboard` client that lets you perform dashboard queries and retrieve relevant data programmatically.

This page shows how to use `Netra.dashboard` to craft dashboard queries, fetch session summaries, and retrieve session statistics.

## Getting Started

The `dashboard` client is available on the main `Netra` entry point after initialization.

```python theme={null}
from netra import Netra

Netra.init(app_name="sample-app")

# Access the dashboard client
Netra.dashboard.query_data(...)
Netra.dashboard.get_session_summary(...)
Netra.dashboard.get_session_stats(...)
```

***

## query\_data

Fetch dashboard data with customizable metrics, dimensions, and filters. This method supports various chart types and aggregation strategies.

<CodeGroup>
  ```python Usage theme={null}
  from netra import Netra
  from netra.dashboard import *

  Netra.init(app_name="sample-app")

  result = Netra.dashboard.query_data(
      scope=Scope.SPANS,
      chart_type=ChartType.LINE_TIME_SERIES,
      metrics=Metrics(
          measure=Measure.TOTAL_COST,
          aggregation=Aggregation.TOTAL_COUNT,
      ),
      dimension=Dimension(
          field=DimensionField.SERVICE,
      ),
      filter=FilterConfig(
          start_time="2026-01-10T00:00:00.000Z",
          end_time="2026-01-14T23:59:59.000Z",
          group_by=GroupBy.DAY,
          filters=[
              Filter(
                  field=FilterField.ENVIRONMENT,
                  operator=Operator.EQUALS,
                  type=Type.STRING,
                  value="production",
              )
          ],
      ),
  )

  print(result)
  ```

  ```python Signature theme={null}
  query_data(
      scope: Scope,
      chart_type: ChartType,
      metrics: Metrics,
      filter: FilterConfig,
      dimension: Dimension | None = None,
  ) -> dict | Any
  ```
</CodeGroup>

### Parameters

| Parameter    | Type           | Description                                            |
| ------------ | -------------- | ------------------------------------------------------ |
| `scope`      | `Scope`        | Scope of data to query (`SPANS` or `TRACES`)           |
| `chart_type` | `ChartType`    | Chart visualization type (controls the response shape) |
| `metrics`    | `Metrics`      | Defines what metric to compute and how to aggregate it |
| `filter`     | `FilterConfig` | Filter configuration constraining the query            |
| `dimension`  | `Dimension?`   | Optional grouping to split results by a dimension      |

### Enums and Types

<AccordionGroup>
  <Accordion title="Scope" icon="bullseye">
    | Value          | Description                       |
    | -------------- | --------------------------------- |
    | `Scope.SPANS`  | Query individual span-level data  |
    | `Scope.TRACES` | Query trace-level aggregated data |
  </Accordion>

  <Accordion title="ChartType" icon="chart-line">
    | Value                        | Description          |
    | ---------------------------- | -------------------- |
    | `ChartType.LINE_TIME_SERIES` | Line chart over time |
    | `ChartType.BAR_TIME_SERIES`  | Bar chart over time  |
    | `ChartType.HORIZONTAL_BAR`   | Horizontal bar chart |
    | `ChartType.VERTICAL_BAR`     | Vertical bar chart   |
    | `ChartType.PIE`              | Pie chart            |
    | `ChartType.NUMBER`           | Single numeric value |
  </Accordion>

  <Accordion title="Metrics" icon="calculator">
    The `Metrics` object defines what to measure and how to aggregate.

    | Field         | Type            | Description                                               |
    | ------------- | --------------- | --------------------------------------------------------- |
    | `metric_name` | `Optional[str]` | Name of metric<br />*(applicable only for custom metric)* |
    | `measure`     | `Measure`       | Measure of the metric                                     |
    | `aggregation` | `Aggregation`   | Aggregation to use                                        |

    **Measure:**

    | Value                     | Description             |
    | ------------------------- | ----------------------- |
    | `Measure.LATENCY`         | Request latency         |
    | `Measure.ERROR_RATE`      | Error rate percentage   |
    | `Measure.PII_COUNT`       | Count of PII detections |
    | `Measure.REQUEST_COUNT`   | Number of requests      |
    | `Measure.TOTAL_COST`      | Total cost in USD       |
    | `Measure.VIOLATIONS`      | Policy violations count |
    | `Measure.TOTAL_TOKENS`    | Total token usage       |
    | `Measure.AUDIO_DURATION`  | Audio Duration          |
    | `Measure.CHARACTER_COUNT` | Character Count         |
    | `Measure.TTFT`            | Time to First Token     |
    | `Measure.CUSTOM`          | Custom Metric           |

    **Aggregation:**

    | Value                     | Description            |
    | ------------------------- | ---------------------- |
    | `Aggregation.AVERAGE`     | Mean value             |
    | `Aggregation.P50`         | 50th percentile        |
    | `Aggregation.P90`         | 90th percentile        |
    | `Aggregation.P95`         | 95th percentile        |
    | `Aggregation.P99`         | 99th percentile        |
    | `Aggregation.MEDIAN`      | Median value           |
    | `Aggregation.PERCENTAGE`  | Percentage calculation |
    | `Aggregation.TOTAL_COUNT` | Sum total              |
    | `Aggregation.SUM`         | Sum of values          |
  </Accordion>

  <Accordion title="FilterConfig" icon="filter">
    | Field        | Type            | Description                                                             |
    | ------------ | --------------- | ----------------------------------------------------------------------- |
    | `start_time` | `str`           | Start of time window (ISO 8601 UTC, e.g., `"2026-01-10T00:00:00.000Z"`) |
    | `end_time`   | `str`           | End of time window (ISO 8601 UTC)                                       |
    | `group_by`   | `GroupBy`       | Time bucket size: `DAY`, `HOUR`, or `MINUTE`                            |
    | `filters`    | `list[Filter]?` | Optional list of filter conditions                                      |
  </Accordion>

  <Accordion title="Filter" icon="filter-list">
    | Field      | Type          | Description                             |
    | ---------- | ------------- | --------------------------------------- |
    | `field`    | `FilterField` | Field to filter on                      |
    | `operator` | `Operator`    | Comparison operator                     |
    | `type`     | `Type`        | Value type                              |
    | `value`    | `Any`         | Value to compare against                |
    | `key`      | `str?`        | Required only for `Type.OBJECT` filters |

    **FilterField values:** `TOTAL_COST`, `SERVICE`, `TENANT_ID`, `USER_ID`, `SESSION_ID`, `ENVIRONMENT`, `LATENCY`, `MODEL_NAME` (Spans only), `MODELS` (Traces only), `METADATA`

    **Operator values:** `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `GREATER_THAN`, `LESS_THAN`, `GREATER_EQUAL_TO`, `LESS_EQUAL_TO`, `ANY_OF`, `NONE_OF`

    **Type values:** `STRING`, `NUMBER`, `BOOLEAN`, `ARRAY_OPTIONS`, `OBJECT`
  </Accordion>

  <Accordion title="Dimension" icon="layer-group">
    | Field   | Type             | Description                                                      |
    | ------- | ---------------- | ---------------------------------------------------------------- |
    | `field` | `DimensionField` | Field to group by                                                |
    | `name`  | `Optional[str]`  | Name of dimension <br />*(applicable only for custom dimension)* |

    **DimensionField values:**

    | Value                        | Supported Scopes |
    | ---------------------------- | ---------------- |
    | `DimensionField.ENVIRONMENT` | Spans, Traces    |
    | `DimensionField.SERVICE`     | Spans only       |
    | `DimensionField.MODEL_NAME`  | Spans only       |
    | `DimensionFIeld.CUSTOM`      | Custom dimension |
  </Accordion>
</AccordionGroup>

<Note>
  If the query scope is `Scope.TRACES`, only `DimensionField.ENVIRONMENT` is supported. The `Scope.SPANS` supports all dimension fields.
</Note>

***

## get\_session\_summary

Retrieve aggregated session metrics including total sessions, costs, latency, and cost breakdown by model.

<CodeGroup>
  ```python Usage theme={null}
  from netra import Netra
  from netra.dashboard import *

  Netra.init(app_name="sample-app")

  result = Netra.dashboard.get_session_summary(
      filter=SessionFilterConfig(
          start_time="2026-01-01T00:00:00.000Z",
          end_time="2026-01-31T23:59:59.000Z",
          filters=[
              SessionFilter(
                  field=SessionFilterField.TENANT_ID,
                  operator=SessionFilterOperator.ANY_OF,
                  type=SessionFilterType.ARRAY,
                  value=["Unilever", "AceTech"]
              ),
              SessionFilter(
                  field=SessionFilterField.SERVICE,
                  operator=SessionFilterOperator.ANY_OF,
                  type=SessionFilterType.ARRAY,
                  value=["openai-chat"]
              ),
              SessionFilter(
                  field=SessionFilterField.ENVIRONMENT,
                  operator=SessionFilterOperator.ANY_OF,
                  type=SessionFilterType.ARRAY,
                  value=["production"]
              )
          ]
      )
  )

  print(result)
  ```

  ```python Signature theme={null}
  get_session_summary(
      filter: SessionFilterConfig
  ) -> dict | Any
  ```
</CodeGroup>

### Parameters

| Parameter | Type                  | Description                        |
| --------- | --------------------- | ---------------------------------- |
| `filter`  | `SessionFilterConfig` | Filter configuration for the query |

### SessionFilterConfig

| Field        | Type                   | Description                         |
| ------------ | ---------------------- | ----------------------------------- |
| `start_time` | `str`                  | Start of time window (ISO 8601 UTC) |
| `end_time`   | `str`                  | End of time window (ISO 8601 UTC)   |
| `filters`    | `list[SessionFilter]?` | Optional list of filter conditions  |

### SessionFilter (Optional)

| Field      | Type                    | Description                                    |
| ---------- | ----------------------- | ---------------------------------------------- |
| `field`    | `SessionFilterField`    | Supports `TENANT_ID`, `ENVIRONMENT`, `SERVICE` |
| `operator` | `SessionFilterOperator` | Currently supports `ANY_OF`                    |
| `type`     | `SessionFilterType`     | Currently supports `ARRAY`                     |
| `value`    | `list[str]`             | List of values to match                        |

### Response

```json theme={null}
{
  "timeRange": {
    "startTime": "2026-01-01T00:00:00.000Z",
    "endTime": "2026-01-31T23:59:59.000Z"
  },
  "data": {
    "totalSessions": 207,
    "totalCost": 0.041807,
    "avgCostPerSession": 0.000202,
    "avgLatencyMs": 8689.83,
    "costByModel": [
      {
        "model": "gpt-4o-mini",
        "cost": 0.041807
      }
    ]
  }
}
```

***

## get\_session\_stats

Fetch a paginated list of sessions with individual session metrics including request count, cost, and duration.

<CodeGroup>
  ```python Usage theme={null}
  from netra import Netra
  from netra.dashboard import *

  Netra.init(app_name="sample-app")

  session_stats = Netra.dashboard.get_session_stats(
      start_time="2026-01-01T00:00:00.000Z",
      end_time="2026-01-31T23:59:59.000Z",
      limit=10,
      cursor=None,
      filters=[
          SessionFilter(
              field=SessionFilterField.TENANT_ID,
              operator=SessionFilterOperator.ANY_OF,
              type=SessionFilterType.ARRAY,
              value=["Unilever", "AceTech"]
          ),
          SessionFilter(
              field=SessionFilterField.SERVICE,
              operator=SessionFilterOperator.ANY_OF,
              type=SessionFilterType.ARRAY,
              value=["openai-chat"]
          ),
          SessionFilter(
              field=SessionFilterField.ENVIRONMENT,
              operator=SessionFilterOperator.ANY_OF,
              type=SessionFilterType.ARRAY,
              value=["production"]
          )
      ],
      sort_field=SortField.START_TIME,
      sort_order=SortOrder.DESC
  )

  print(session_stats.data)

  # Pagination
  if session_stats.has_next_page:
      next_page = Netra.dashboard.get_session_stats(
          start_time="2026-01-01T00:00:00.000Z",
          end_time="2026-01-31T23:59:59.000Z",
          limit=10,
          cursor=session_stats.next_cursor,
          filters=[
              SessionFilter(
                  field=SessionFilterField.TENANT_ID,
                  operator=SessionFilterOperator.ANY_OF,
                  type=SessionFilterType.ARRAY,
                  value=["Unilever", "AceTech"]
              ),
              SessionFilter(
                  field=SessionFilterField.SERVICE,
                  operator=SessionFilterOperator.ANY_OF,
                  type=SessionFilterType.ARRAY,
                  value=["openai-chat"]
              ),
              SessionFilter(
                  field=SessionFilterField.ENVIRONMENT,
                  operator=SessionFilterOperator.ANY_OF,
                  type=SessionFilterType.ARRAY,
                  value=["production"]
              )
          ],
          sort_field=SortField.START_TIME,
          sort_order=SortOrder.DESC
      )
      print(next_page.data)
  ```

  ```python Signature theme={null}
  get_session_stats(
      start_time: str,
      end_time: str,
      filters: Optional[List[SessionFilter]] = None,
      limit: Optional[int] = None,
      cursor: Optional[str] = None,
      sort_field: Optional[SortField] = None,
      sort_order: Optional[SortOrder] = None,
  ) -> SessionStatsResult
  ```
</CodeGroup>

### Parameters

| Parameter    | Type                   | Description                          |
| ------------ | ---------------------- | ------------------------------------ |
| `start_time` | `str`                  | Start of time window (ISO 8601 UTC)  |
| `end_time`   | `str`                  | End of time window (ISO 8601 UTC)    |
| `filters`    | `list[SessionFilter]?` | Optional filter conditions           |
| `limit`      | `int?`                 | Maximum results per page             |
| `cursor`     | `str?`                 | Pagination cursor from previous page |
| `sort_field` | `SortField?`           | Field to sort by                     |
| `sort_order` | `SortOrder?`           | Sort direction                       |

### Sorting Options

<AccordionGroup>
  <Accordion title="SortField" icon="arrow-down-a-z">
    | Value                      | Description                |
    | -------------------------- | -------------------------- |
    | `SortField.SESSION_ID`     | Sort by session ID         |
    | `SortField.START_TIME`     | Sort by session start time |
    | `SortField.TOTAL_REQUESTS` | Sort by request count      |
    | `SortField.TOTAL_COST`     | Sort by total cost         |
  </Accordion>

  <Accordion title="SortOrder" icon="arrow-up-down">
    | Value            | Description      |
    | ---------------- | ---------------- |
    | `SortOrder.ASC`  | Ascending order  |
    | `SortOrder.DESC` | Descending order |
  </Accordion>
</AccordionGroup>

### Response

```json theme={null}
SessionStatsResult(
    data=[
        {
         "sessionId": "0acd79e0-526e-40cc-91e9-4010711de0ed",
         "sessionStartTime": "2026-02-23 11:59:58.785",
         "totalRequests": "1",
         "totalCost": 0.0012775,
         "costByModel": {
           "gpt-4o": 0.0012775
          },
         "sessionDuration": "4.05s",
         "cursor": "MjAyNi0wMi0yMyAxMTo1OTo1OC43ODV8MGFjZDc5ZTAtNTI2ZS00MGNjLTkxZTktNDAxMDcxMWRlMGVk"
        },
        {
         "sessionId": "03d000d0-0b16-4688-a83b-291ed489c281",
         "sessionStartTime": "2026-02-23 11:59:14.233",
         "totalRequests": "2",
         "totalCost": 0.00161175,
         "costByModel": {
           "gpt-4o-mini": 0.00010425,
            "gpt-4o": 0.0015075
        },
        "sessionDuration": "1m 16.27s",
        "cursor": "MjAyNi0wMi0yMyAxMTo1OToxNC4yMzN8MDNkMDAwZDAtMGIxNi00Njg4LWE4M2ItMjkxZWQ0ODljMjgx"
    }],
    has_next_page=True,
    next_cursor="MjAyNi0wMS0yMiAwOTo1MzoyNy4xNjN8ODMzNmQwOTYtZjNiNS00ZTk5LWE1ZjEtYTk2OTkxMjlmNDFh",
)
```

## iter\_session\_stats

Stream over all pages of session stats until completion. This iterator handles pagination automatically.

<CodeGroup>
  ```python Usage theme={null}
  from netra import Netra
  from netra.dashboard import *

  Netra.init(app_name="sample-app")

  for session in Netra.dashboard.iter_session_stats(
      start_time="2026-01-01T00:00:00.000Z",
      end_time="2026-01-31T23:59:59.000Z",
      filters=[
          SessionFilter(
              field=SessionFilterField.TENANT_ID,
              operator=SessionFilterOperator.ANY_OF,
              type=SessionFilterType.ARRAY,
              value=["Unilever", "AceTech"]
          ),
          SessionFilter(
              field=SessionFilterField.SERVICE,
              operator=SessionFilterOperator.ANY_OF,
              type=SessionFilterType.ARRAY,
              value=["openai-chat"]
          ),
          SessionFilter(
              field=SessionFilterField.ENVIRONMENT,
              operator=SessionFilterOperator.ANY_OF,
              type=SessionFilterType.ARRAY,
              value=["production"]
          )
      ],
      sort_field=SortField.START_TIME,
      sort_order=SortOrder.DESC
  ):
      print(session)
  ```

  ```python Signature theme={null}
  iter_session_stats(
      start_time: str,
      end_time: str,
      filters: Optional[List[SessionFilter]] = None,
      sort_field: Optional[SortField] = None,
      sort_order: Optional[SortOrder] = None,
  ) -> Iterator[SessionStatsResult]
  ```
</CodeGroup>

### Parameters

| Parameter    | Type                   | Description                         |
| ------------ | ---------------------- | ----------------------------------- |
| `start_time` | `str`                  | Start of time window (ISO 8601 UTC) |
| `end_time`   | `str`                  | End of time window (ISO 8601 UTC)   |
| `filters`    | `list[SessionFilter]?` | Optional filter conditions          |
| `sort_field` | `SortField?`           | Field to sort by                    |
| `sort_order` | `SortOrder?`           | Sort direction                      |

### Response

```json theme={null}
  {
    "sessionId": "0acd79e0-526e-40cc-91e9-4010711de0ed",
    "sessionStartTime": "2026-02-23 11:59:58.785",
    "totalRequests": 1,
    "totalCost": 0.0012775,
    "costByModel": {
      "gpt-4o": 0.0012775
    },
    "sessionDuration": "4.05s",
    "cursor": "MjAyNi0wMi0yMyAxMTo1OTo1OC43ODV8MGFjZDc5ZTAtNTI2ZS00MGNjLTkxZTktNDAxMDcxMWRlMGVk"
  }
  {
    "sessionId": "03d000d0-0b16-4688-a83b-291ed489c281",
    "sessionStartTime": "2026-02-23 11:59:14.233",
    "totalRequests": 37,
    "totalCost": 0.02144675,
    "costByModel": {
      "gpt-4o-mini": 0.00010425,
      "gpt-4o": 0.0213425
    },
    "sessionDuration": "22hr 19m",
    "cursor": "MjAyNi0wMi0yMyAxMTo1OToxNC4yMzN8MDNkMDAwZDAtMGIxNi00Njg4LWE4M2ItMjkxZWQ0ODljMjgx"
  }
  {
    "sessionId": "fe19a082-1b4f-4be9-a75c-91a609c948ad",
    "sessionStartTime": "2026-02-23 04:45:26.156",
    "totalRequests": 1,
    "totalCost": 0.0000897,
    "costByModel": {
      "gpt-4o-mini": 0.0000897
    },
    "sessionDuration": "3.76s",
    "cursor": "MjAyNi0wMi0yMyAwNDo0NToyNi4xNTZ8ZmUxOWEwODItMWI0Zi00YmU5LWE3NWMtOTFhNjA5Yzk0OGFk"
  }
```

<Tip>
  Use `iter_session_stats` when you need to process all sessions without manually handling pagination. The iterator fetches pages on-demand as you iterate.
</Tip>

***

## Complete Example

```python theme={null}
from netra import Netra
from netra.dashboard import *

# Initialize the SDK
Netra.init(
    app_name="analytics-app",
    headers="x-api-key=your-api-key",
)

# Query cost trends over time
cost_trends = Netra.dashboard.query_data(
    scope=Scope.SPANS,
    chart_type=ChartType.LINE_TIME_SERIES,
    metrics=Metrics(
        measure=Measure.TOTAL_COST,
        aggregation=Aggregation.TOTAL_COUNT,
    ),
    dimension=Dimension(field=DimensionField.SERVICE),
    filter=FilterConfig(
        start_time="2026-01-01T00:00:00.000Z",
        end_time="2026-01-31T23:59:59.000Z",
        group_by=GroupBy.DAY,
    ),
)

# Get session summary for specific tenants, services, and environments
summary = Netra.dashboard.get_session_summary(
    filter=SessionFilterConfig(
        start_time="2026-01-01T00:00:00.000Z",
        end_time="2026-01-31T23:59:59.000Z",
        filters=[
            SessionFilter(
                field=SessionFilterField.TENANT_ID,
                operator=SessionFilterOperator.ANY_OF,
                type=SessionFilterType.ARRAY,
                value=["TenantA", "TenantB"]
            ),
            SessionFilter(
                field=SessionFilterField.SERVICE,
                operator=SessionFilterOperator.ANY_OF,
                type=SessionFilterType.ARRAY,
                value=["openai-chat"]
            ),
            SessionFilter(
                field=SessionFilterField.ENVIRONMENT,
                operator=SessionFilterOperator.ANY_OF,
                type=SessionFilterType.ARRAY,
                value=["production"]
            )
        ]
    )
)

# Iterate through all sessions
for session in Netra.dashboard.iter_session_stats(
    start_time="2026-01-01T00:00:00.000Z",
    end_time="2026-01-31T23:59:59.000Z",
    sort_field=SortField.TOTAL_COST,
    sort_order=SortOrder.DESC
):
    print(f"Session {session.session_id}: ${session.total_cost:.4f}")
```

## Next Steps

* [Usage Utilities](/usage/usage-utilities) - Query token usage and trace data
* [Python SDK Reference](/sdk-reference/sdk/python) - Complete SDK documentation
* [Custom Dashboard](/Dashboard/Custom-dashboard) - Build custom dashboards