Skip to main content
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. 
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. 
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)

​
Parameters

ParameterTypeDescription
scopeScopeScope of data to query (SPANS or TRACES)
chart_typeChartTypeChart visualization type (controls the response shape)
metricsMetricsDefines what metric to compute and how to aggregate it
filterFilterConfigFilter configuration constraining the query
dimensionDimension?Optional grouping to split results by a dimension

​
Enums and Types

ValueDescription
Scope.SPANSQuery individual span-level data
Scope.TRACESQuery trace-level aggregated data
ValueDescription
ChartType.LINE_TIME_SERIESLine chart over time
ChartType.BAR_TIME_SERIESBar chart over time
ChartType.HORIZONTAL_BARHorizontal bar chart
ChartType.VERTICAL_BARVertical bar chart
ChartType.PIEPie chart
ChartType.NUMBERSingle numeric value
The Metrics object defines what to measure and how to aggregate.Measure:
ValueDescription
Measure.LATENCYRequest latency
Measure.ERROR_RATEError rate percentage
Measure.PII_COUNTCount of PII detections
Measure.REQUEST_COUNTNumber of requests
Measure.TOTAL_COSTTotal cost in USD
Measure.VIOLATIONSPolicy violations count
Measure.TOTAL_TOKENSTotal token usage
Aggregation:
ValueDescription
Aggregation.AVERAGEMean value
Aggregation.P5050th percentile
Aggregation.P9090th percentile
Aggregation.P9595th percentile
Aggregation.P9999th percentile
Aggregation.MEDIANMedian value
Aggregation.PERCENTAGEPercentage calculation
Aggregation.TOTAL_COUNTSum total
FieldTypeDescription
start_timestrStart of time window (ISO 8601 UTC, e.g., "2026-01-10T00:00:00.000Z")
end_timestrEnd of time window (ISO 8601 UTC)
group_byGroupByTime bucket size: DAY, HOUR, or MINUTE
filterslist[Filter]?Optional list of filter conditions
FieldTypeDescription
fieldFilterFieldField to filter on
operatorOperatorComparison operator
typeTypeValue type
valueAnyValue to compare against
keystr?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), METADATAOperator values: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH, GREATER_THAN, LESS_THAN, GREATER_EQUAL_TO, LESS_EQUAL_TO, ANY_OF, NONE_OFType values: STRING, NUMBER, BOOLEAN, ARRAY_OPTIONS, OBJECT
FieldTypeDescription
fieldDimensionFieldField to group by
DimensionField values:
ValueSupported Scopes
DimensionField.ENVIRONMENTSpans, Traces
DimensionField.SERVICESpans only
DimensionField.MODEL_NAMESpans only
If the query scope is Scope.TRACES, only DimensionField.ENVIRONMENT is supported. The Scope.SPANS supports all dimension fields.

​
get_session_summary

Retrieve aggregated session metrics including total sessions, costs, latency, and cost breakdown by model. 
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)

​
Parameters

ParameterTypeDescription
filterSessionFilterConfigFilter configuration for the query

​
SessionFilterConfig

FieldTypeDescription
start_timestrStart of time window (ISO 8601 UTC)
end_timestrEnd of time window (ISO 8601 UTC)
filterslist[SessionFilter]?Optional list of filter conditions

​
SessionFilter (Optional)

FieldTypeDescription
fieldSessionFilterFieldSupports TENANT_ID, ENVIRONMENT, SERVICE
operatorSessionFilterOperatorCurrently supports ANY_OF
typeSessionFilterTypeCurrently supports ARRAY
valuelist[str]List of values to match

​
get_session_stats

Fetch a paginated list of sessions with individual session metrics including request count, cost, and duration. 
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)

​
Parameters

ParameterTypeDescription
start_timestrStart of time window (ISO 8601 UTC)
end_timestrEnd of time window (ISO 8601 UTC)
filterslist[SessionFilter]?Optional filter conditions
limitint?Maximum results per page
cursorstr?Pagination cursor from previous page
sort_fieldSortField?Field to sort by
sort_orderSortOrder?Sort direction

​
Sorting Options

ValueDescription
SortField.SESSION_IDSort by session ID
SortField.START_TIMESort by session start time
SortField.TOTAL_REQUESTSSort by request count
SortField.TOTAL_COSTSort by total cost
ValueDescription
SortOrder.ASCAscending order
SortOrder.DESCDescending order

​
iter_session_stats

Stream over all pages of session stats until completion. This iterator handles pagination automatically. 
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)

​
Parameters

ParameterTypeDescription
start_timestrStart of time window (ISO 8601 UTC)
end_timestrEnd of time window (ISO 8601 UTC)
filterslist[SessionFilter]?Optional filter conditions
sort_fieldSortField?Field to sort by
sort_orderSortOrder?Sort direction
Use iter_session_stats when you need to process all sessions without manually handling pagination. The iterator fetches pages on-demand as you iterate.

​
Complete Example

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

Last modified on February 3, 2026