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. 
import { Netra } from "netra-sdk-js";

const client = new Netra({
  apiKey: "your-api-key",
});

// Access the dashboard client
await client.dashboard.queryData(...);
await client.dashboard.getSessionSummary(...);
await client.dashboard.getSessionStats(...);

​
queryData

Fetch dashboard data with customizable metrics, dimensions, and filters. This method supports various chart types and aggregation strategies. 
import { Netra } from "netra-sdk-js";
import {
  Scope,
  ChartType,
  Measure,
  Aggregation,
  DimensionField,
  GroupBy,
  FilterField,
  Operator,
  FilterType,
} from "netra-sdk-js/api/dashboard";

const client = new Netra({ apiKey: "..." });

const result = await client.dashboard.queryData({
  scope: Scope.SPANS,
  chartType: ChartType.LINE_TIME_SERIES,
  metrics: {
    measure: Measure.TOTAL_COST,
    aggregation: Aggregation.TOTAL_COUNT,
  },
  dimension: {
    field: DimensionField.SERVICE,
  },
  filter: {
    startTime: "2026-01-10T00:00:00.000Z",
    endTime: "2026-01-14T23:59:59.000Z",
    groupBy: GroupBy.DAY,
    filters: [
      {
        field: FilterField.ENVIRONMENT,
        operator: Operator.EQUALS,
        type: FilterType.STRING,
        value: "production",
      },
    ],
  },
});

console.log(result);

​
Parameters

ParameterTypeDescription
scopeScopeScope of data to query (SPANS or TRACES)
chartTypeChartTypeChart 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
startTimestringStart of time window (ISO 8601 UTC, e.g., "2026-01-10T00:00:00.000Z")
endTimestringEnd of time window (ISO 8601 UTC)
groupByGroupByTime bucket size: DAY, HOUR, or MINUTE
filtersFilter[]?Optional list of filter conditions
FieldTypeDescription
fieldFilterField | stringField to filter on
operatorOperatorComparison operator
typeFilterTypeValue type
valueanyValue to compare against
keystring?Required only for FilterType.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_OFFilterType 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.

​
getSessionSummary

Retrieve aggregated session metrics including total sessions, costs, latency, and cost breakdown by model. 
import { Netra } from "netra-sdk-js";
import {
  SessionFilterField,
  SessionOperator,
  SessionFilterType,
} from "netra-sdk-js/api/dashboard";

const client = new Netra({ apiKey: "..." });

const result = await client.dashboard.getSessionSummary({
  startTime: "2026-01-01T00:00:00.000Z",
  endTime: "2026-01-31T23:59:59.000Z",
  filters: [
    {
      field: SessionFilterField.TENANT_ID,
      operator: SessionOperator.ANY_OF,
      type: SessionFilterType.ARRAY,
      value: ["Unilever", "AceTech"],
    },
  ],
});

console.log(result);

​
Parameters

ParameterTypeDescription
filterSessionFilterConfigFilter configuration for the query

​
SessionFilterConfig

FieldTypeDescription
startTimestringStart of time window (ISO 8601 UTC)
endTimestringEnd of time window (ISO 8601 UTC)
filtersSessionFilter[]?Optional list of filter conditions

​
SessionFilter (Optional)

FieldTypeDescription
fieldSessionFilterFieldSupports TENANT_ID
operatorSessionOperatorCurrently supports ANY_OF
typeSessionFilterTypeCurrently supports ARRAY
valuestring[]List of values to match

​
getSessionStats

Fetch a paginated list of sessions with individual session metrics including request count, cost, and duration. 
import { Netra } from "netra-sdk-js";
import {
  SessionFilterField,
  SessionOperator,
  SessionFilterType,
  SortField,
  SortOrder,
} from "netra-sdk-js/api/dashboard";

const client = new Netra({ apiKey: "..." });

const sessionStats = await client.dashboard.getSessionStats(
  "2026-01-01T00:00:00.000Z", // startTime
  "2026-01-31T23:59:59.000Z", // endTime
  10,                         // limit
  [                           // filters
    {
      field: SessionFilterField.TENANT_ID,
      operator: SessionOperator.ANY_OF,
      type: SessionFilterType.ARRAY,
      value: ["Unilever", "AceTech"],
    },
  ],
  undefined,                  // cursor
  SortField.START_TIME,       // sortField
  SortOrder.DESC              // sortOrder
);

if (sessionStats) {
  console.log(sessionStats.data);

  // Pagination
  if (sessionStats.hasNextPage && sessionStats.nextCursor) {
    const nextPage = await client.dashboard.getSessionStats(
      "2026-01-01T00:00:00.000Z",
      "2026-01-31T23:59:59.000Z",
      10,
      [
        {
          field: SessionFilterField.TENANT_ID,
          operator: SessionOperator.ANY_OF,
          type: SessionFilterType.ARRAY,
          value: ["Unilever", "AceTech"],
        },
      ],
      sessionStats.nextCursor,
      SortField.START_TIME,
      SortOrder.DESC
    );
    console.log(nextPage?.data);
  }
}

​
Parameters

ParameterTypeDescription
startTimestringStart of time window (ISO 8601 UTC)
endTimestringEnd of time window (ISO 8601 UTC)
limitnumber?Maximum results per page (default: 10)
filtersSessionFilter[]?Optional filter conditions
cursorstring?Pagination cursor from previous page
sortFieldSortField?Field to sort by
sortOrderSortOrder?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

​
iterSessionStats

Stream over all pages of session stats until completion. This iterator handles pagination automatically. 
import { Netra } from "netra-sdk-js";
import {
  SessionFilterField,
  SessionOperator,
  SessionFilterType,
  SortField,
  SortOrder,
} from "netra-sdk-js/api/dashboard";

const client = new Netra({ apiKey: "..." });

const iterator = client.dashboard.iterSessionStats(
  "2026-01-01T00:00:00.000Z",
  "2026-01-31T23:59:59.000Z",
  [
    {
      field: SessionFilterField.TENANT_ID,
      operator: SessionOperator.ANY_OF,
      type: SessionFilterType.ARRAY,
      value: ["Unilever", "AceTech"],
    },
  ],
  SortField.START_TIME,
  SortOrder.DESC
);

for await (const session of iterator) {
  console.log(session);
}

​
Parameters

ParameterTypeDescription
startTimestringStart of time window (ISO 8601 UTC)
endTimestringEnd of time window (ISO 8601 UTC)
filtersSessionFilter[]?Optional filter conditions
sortFieldSortField?Field to sort by
sortOrderSortOrder?Sort direction
Use iterSessionStats when you need to process all sessions without manually handling pagination. The iterator fetches pages on-demand as you iterate.

​
Complete Example

import { Netra } from "netra-sdk-js";
import {
  Scope,
  ChartType,
  Measure,
  Aggregation,
  DimensionField,
  GroupBy,
  SessionFilterField,
  SessionOperator,
  SessionFilterType,
  SortField,
  SortOrder,
} from "netra-sdk-js/api/dashboard";

async function main() {
  // Initialize the SDK
  const client = new Netra({
    apiKey: "your-api-key",
  });

  // Query cost trends over time
  const costTrends = await client.dashboard.queryData({
    scope: Scope.SPANS,
    chartType: ChartType.LINE_TIME_SERIES,
    metrics: {
      measure: Measure.TOTAL_COST,
      aggregation: Aggregation.TOTAL_COUNT,
    },
    dimension: {
      field: DimensionField.SERVICE,
    },
    filter: {
      startTime: "2026-01-01T00:00:00.000Z",
      endTime: "2026-01-31T23:59:59.000Z",
      groupBy: GroupBy.DAY,
    },
  });

  // Get session summary for specific tenants
  const summary = await client.dashboard.getSessionSummary({
    startTime: "2026-01-01T00:00:00.000Z",
    endTime: "2026-01-31T23:59:59.000Z",
    filters: [
      {
        field: SessionFilterField.TENANT_ID,
        operator: SessionOperator.ANY_OF,
        type: SessionFilterType.ARRAY,
        value: ["TenantA", "TenantB"],
      },
    ],
  });

  // Iterate through all sessions
  const iterator = client.dashboard.iterSessionStats(
    "2026-01-01T00:00:00.000Z",
    "2026-01-31T23:59:59.000Z",
    undefined,
    SortField.TOTAL_COST,
    SortOrder.DESC
  );

  for await (const session of iterator) {
    console.log(
      `Session ${session.session_id}: $${session.totalCost.toFixed(4)}`
    );
  }
}

main();

​
Next Steps

Last modified on February 10, 2026