Dashboard Query - What is Netra? | Technical documentation

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, retrieve session statistics, and load full session details.

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(...)
Netra.dashboard.get_session_details(...)

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)

query_data(
    scope: Scope,
    chart_type: ChartType,
    metrics: Metrics,
    filter: FilterConfig,
    dimension: Dimension | None = None,
) -> dict | Any

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

Scope

Value	Description
`Scope.SPANS`	Query individual span-level data
`Scope.TRACES`	Query trace-level aggregated data

ChartType

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

Metrics

The Metrics object defines what to measure and how to aggregate.

Field	Type	Description
`metric_name`	`Optional[str]`	Name of metric (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

FilterConfig

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

Filter

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), 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

Dimension

Field	Type	Description
`field`	`DimensionField`	Field to group by
`name`	`Optional[str]`	Name of dimension (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

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"]
            ),
            SessionFilter(
                field=SessionFilterField.USER_ID,
                operator=SessionFilterOperator.ANY_OF,
                type=SessionFilterType.ARRAY,
                value=["user-123", "user-456"]
            )
        ]
    )
)

print(result)

get_session_summary(
    filter: SessionFilterConfig
) -> dict | Any

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`, `USER_ID`
`operator`	`SessionFilterOperator`	Currently supports `ANY_OF`
`type`	`SessionFilterType`	Currently supports `ARRAY`
`value`	`list[str]`	List of values to match

Response

{
  "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_details

Retrieve full details for a single session, including every trace with tokens, costs, models, inputs/outputs, and tool calls.

get_session_details is available in the Python SDK only.

from netra import Netra

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

detail = Netra.dashboard.get_session_details(
    session_id="0acd79e0-526e-40cc-91e9-4010711de0ed"
)

print(detail["sessionId"])
for trace in detail["traces"]:
    print(trace["traceId"], trace["cost"]["totalCost"], trace["toolCalls"])

get_session_details(
    session_id: str
) -> dict | Any

Parameters

Parameter	Type	Description
`session_id`	`str`	Session identifier

Response

{
  "sessionId": "0acd79e0-526e-40cc-91e9-4010711de0ed",
  "traces": [
    {
      "traceId": "de51208be1ae032057381f162cbcea9b",
      "traceName": "openai.chat",
      "startTime": "2026-01-15T10:30:00Z",
      "endTime": "2026-01-15T10:30:04Z",
      "latencyMs": 4050,
      "input": "What is the refund policy?",
      "output": "You can request a refund within 30 days...",
      "tokens": {
        "promptTokens": 120,
        "completionTokens": 85,
        "cachedTokens": 0,
        "cacheCreationTokens": 0,
        "totalTokens": 205
      },
      "cost": {
        "promptTokensCost": 0.000018,
        "completionTokensCost": 0.000051,
        "cachedTokensCost": 0,
        "cacheCreationTokensCost": 0,
        "totalCost": 0.000069
      },
      "models": ["gpt-4o-mini"],
      "toolCalls": [
        {
          "toolName": "lookup_policy",
          "toolCallCount": 1
        }
      ]
    }
  ]
}

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"]
        ),
        SessionFilter(
            field=SessionFilterField.USER_ID,
            operator=SessionFilterOperator.ANY_OF,
            type=SessionFilterType.ARRAY,
            value=["user-123"]
        )
    ],
    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"]
            ),
            SessionFilter(
                field=SessionFilterField.USER_ID,
                operator=SessionFilterOperator.ANY_OF,
                type=SessionFilterType.ARRAY,
                value=["user-123"]
            )
        ],
        sort_field=SortField.START_TIME,
        sort_order=SortOrder.DESC
    )
    print(next_page.data)

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

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

SortField

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

SortOrder

Value	Description
`SortOrder.ASC`	Ascending order
`SortOrder.DESC`	Descending order

Response

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.

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)

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]

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

  {
    "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"
  }

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, environments, and users
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"]
            ),
            SessionFilter(
                field=SessionFilterField.USER_ID,
                operator=SessionFilterOperator.ANY_OF,
                type=SessionFilterType.ARRAY,
                value=["user-123"]
            )
        ]
    )
)

# 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}")

# Load full detail for a specific session
detail = Netra.dashboard.get_session_details(
    session_id="0acd79e0-526e-40cc-91e9-4010711de0ed"
)
print(detail["sessionId"], len(detail["traces"]))

Next Steps

Usage Utilities - Query token usage and trace data
Python SDK Reference - Complete SDK documentation
Custom Dashboard - Build custom dashboards

​Getting Started

​query_data

​Parameters

​Enums and Types

​get_session_summary

​Parameters

​SessionFilterConfig

​SessionFilter (Optional)

​Response

​get_session_details

​Parameters

​Response

​get_session_stats

​Parameters

​Sorting Options

​Response

​iter_session_stats

​Parameters

​Response

​Complete Example

​Next Steps

Getting Started

query_data

Parameters

Enums and Types

get_session_summary

Parameters

SessionFilterConfig

SessionFilter (Optional)

Response

get_session_details

Parameters

Response

get_session_stats

Parameters

Sorting Options

Response

iter_session_stats

Parameters

Response

Complete Example

Next Steps