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

queryData(params: QueryDataParams): Promise<QueryResponse | null>

// QueryDataParams interface
interface QueryDataParams {
  scope: Scope;
  chartType: ChartType;
  metrics: Metrics;
  filter: FilterConfig;
  dimension?: Dimension;
}

Parameters

Parameter	Type	Description
`scope`	`Scope`	Scope of data to query (`SPANS` or `TRACES`)
`chartType`	`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.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

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

FilterConfig

Field	Type	Description
`startTime`	`string`	Start of time window (ISO 8601 UTC, e.g., `"2026-01-10T00:00:00.000Z"`)
`endTime`	`string`	End of time window (ISO 8601 UTC)
`groupBy`	`GroupBy`	Time bucket size: `DAY`, `HOUR`, or `MINUTE`
`filters`	`Filter[]?`	Optional list of filter conditions

Filter

Field	Type	Description
`field`	`FilterField	string`	Field to filter on
`operator`	`Operator`	Comparison operator
`type`	`FilterType`	Value type
`value`	`any`	Value to compare against
`key`	`string?`	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

Dimension

Field	Type	Description
`field`	`DimensionField`	Field to group by

DimensionField values:

Value	Supported Scopes
`DimensionField.ENVIRONMENT`	Spans, Traces
`DimensionField.SERVICE`	Spans only
`DimensionField.MODEL_NAME`	Spans 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);

getSessionSummary(filter: SessionFilterConfig): Promise<any | null>

// SessionFilterConfig interface
interface SessionFilterConfig {
  startTime: string;
  endTime: string;
  filters?: SessionFilter[];
}

Parameters

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

SessionFilterConfig

Field	Type	Description
`startTime`	`string`	Start of time window (ISO 8601 UTC)
`endTime`	`string`	End of time window (ISO 8601 UTC)
`filters`	`SessionFilter[]?`	Optional list of filter conditions

SessionFilter (Optional)

Field	Type	Description
`field`	`SessionFilterField`	Supports `TENANT_ID`
`operator`	`SessionOperator`	Currently supports `ANY_OF`
`type`	`SessionFilterType`	Currently supports `ARRAY`
`value`	`string[]`	List of values to match

| value | string[] | 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
      }
    ]
  }
}

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);
  }
}

getSessionStats(
  startTime: string,
  endTime: string,
  limit?: number,
  filters?: SessionFilter[],
  cursor?: string,
  sortField?: SortField,
  sortOrder?: SortOrder
): Promise<SessionStatsResult | null>

Parameters

Parameter	Type	Description
`startTime`	`string`	Start of time window (ISO 8601 UTC)
`endTime`	`string`	End of time window (ISO 8601 UTC)
`limit`	`number?`	Maximum results per page (default: 10)
`filters`	`SessionFilter[]?`	Optional filter conditions
`cursor`	`string?`	Pagination cursor from previous page
`sortField`	`SortField?`	Field to sort by
`sortOrder`	`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

{
  "data": [
    {
      "sessionId": "00973697-f64b-4144-a42d-6845f5d149e4",
      "sessionStartTime": "2026-01-22 09:54:51.210",
      "totalRequests": 1,
      "totalCost": 0.0000885,
      "sessionDuration": "3.15s",
      "cursor": "MjAyNi0wMS0yMiAwOTo1NDo1MS4yMTB8MDA5NzM2OTctZjY0Yi00MTQ0LWE0MmQtNjg0NWY1ZDE0OWU0"
    },
    {
      "sessionId": "48827b92-24fa-4278-b559-a982d1ddee96",
      "sessionStartTime": "2026-01-22 09:54:47.563",
      "totalRequests": 1,
      "totalCost": 0.00012465,
      "sessionDuration": "3.65s",
      "cursor": "MjAyNi0wMS0yMiAwOTo1NDo0Ny41NjN8NDg4MjdiOTItMjRmYS00Mjc4LWI1NTktYTk4MmQxZGRlZTk2"
    }
  ],
  "hasNextPage": true,
  "nextCursor": "MjAyNi0wMS0yMiAwOTo1MzoyNy4xNjN8ODMzNmQwOTYtZjNiNS00ZTk5LWE1ZjEtYTk2OTkxMjlmNDFh"
}

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);
}

iterSessionStats(
  startTime: string,
  endTime: string,
  filters?: SessionFilter[],
  sortField?: SortField,
  sortOrder?: SortOrder
): AsyncGenerator<SessionStatsData, void, unknown>

Parameters

Parameter	Type	Description
`startTime`	`string`	Start of time window (ISO 8601 UTC)
`endTime`	`string`	End of time window (ISO 8601 UTC)
`filters`	`SessionFilter[]?`	Optional filter conditions
`sortField`	`SortField?`	Field to sort by
`sortOrder`	`SortOrder?`	Sort direction

Response

{
  "sessionId": "sess_abc123def456",
  "startTime": "2026-01-15T10:23:45.000Z",
  "totalRequests": 12,
  "totalCost": 0.0347,
  "sessionDuration": "4m 32s",
  "cursor": "eyJzZXNzaW9uX2lkIjoic2Vzc19hYmMxMjNkZWY0NTYifQ=="
}
{
  "sessionId": "sess_xyz789ghi012",
  "startTime": "2026-01-14T08:15:30.000Z",
  "totalRequests": 5,
  "totalCost": 0.0123,
  "sessionDuration": "1m 15s",
  "cursor": "eyJzZXNzaW9uX2lkIjoic2Vzc194eXo3ODlnaGkwMTIifQ=="
}
{
  "sessionId": "sess_mno345pqr678",
  "startTime": "2026-01-12T14:50:10.000Z",
  "totalRequests": 28,
  "totalCost": 0.0891,
  "sessionDuration": "12m 08s",
  "cursor": "eyJzZXNzaW9uX2lkIjoic2Vzc19tbm8zNDVwcXI2NzgifQ=="
}

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

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

​Getting Started

​queryData

​Parameters

​Enums and Types

​getSessionSummary

​Parameters

​SessionFilterConfig

​SessionFilter (Optional)

​Response

​getSessionStats

​Parameters

​Sorting Options

​Response

​iterSessionStats

​Parameters

​Response

​Complete Example

​Next Steps

Getting Started

queryData

Parameters

Enums and Types

getSessionSummary

Parameters

SessionFilterConfig

SessionFilter (Optional)

Response

getSessionStats

Parameters

Sorting Options

Response

iterSessionStats

Parameters

Response

Complete Example

Next Steps