Dashboards

Reference for client.dashboards in the Future AGI Python and TypeScript SDKs: dashboards.create, dashboards.delete, dashboards.filter_values, dashboards.get, dashboards.list, dashboards.query and 7 more.

client.dashboards on fi.Client (Python) and client.dashboards on Client from @future-agi/sdk (TypeScript), with the nested resources client.dashboards.metrics, client.dashboards.widgets. The models these methods return are on Observability response models; how arguments, pagination, errors and strict mode work is in the overview.

Methods

MethodDescription
dashboards.createCreate an empty dashboard in the current workspace; add widgets with create_dashboard_widget.
dashboards.deleteDelete a dashboard and the widgets on it.
dashboards.filter_valuesList the distinct values of a metric or attribute for use in dashboard filters.
dashboards.getReturn a dashboard and its widgets by identifier.
dashboards.listList dashboards in the current workspace with their widget counts.
dashboards.queryRun an ad-hoc dashboard query (time_range and metrics, with optional filters and breakdowns) and return chart data without saving a widget.
dashboards.updateUpdate the name and/or description of an existing dashboard (a partial update).
dashboards.metrics.listList the metrics available to dashboard queries across traces, datasets, and simulations.
dashboards.widgets.createAdd a widget to a dashboard.
dashboards.widgets.getReturn a dashboard widget, including its query_config and chart_config.
dashboards.widgets.listList the widgets on a dashboard.
dashboards.widgets.queryExecute a saved widget’s query and return its chart data.
dashboards.widgets.updateUpdate selected fields on a dashboard widget, such as its query_config, chart_config, or layout.

client.dashboards

dashboards.create

Create an empty dashboard in the current workspace; add widgets with create_dashboard_widget.

POST /tracer/dashboard/

MCP tool: create_dashboard

result = client.dashboards.create(name="your-name")
const result = await client.dashboards.create({ name: "your-name" });
Signature
client.dashboards.create(
    *,
    name: str,
    description: str | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardDetail
client.dashboards.create(params: DashboardsCreateParams, options?: RequestOptions): Promise<models.DashboardDetail>

export interface DashboardsCreateParams {
  name: string;
  description?: string | null;
}

Parameters

name string Required
description string Optional

Returns

DashboardDetail.

dashboards.delete

Delete a dashboard and the widgets on it. This is the only way to remove a dashboard created earlier.

DELETE /tracer/dashboard/{id}/

MCP tool: delete_dashboard

result = client.dashboards.delete("your-id")
const result = await client.dashboards.delete("your-id");
Signature
client.dashboards.delete(
    id: str,
    *,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> Any
client.dashboards.delete(id: string, options?: RequestOptions): Promise<unknown>

Parameters

id string Required

Positional argument id.

Returns

The decoded response. The contract does not describe its shape, so it is untyped.

dashboards.filter_values

List the distinct values of a metric or attribute for use in dashboard filters.

GET /tracer/dashboard/filter_values/

MCP tool: get_dashboard_filter_values

result = client.dashboards.filter_values()
const result = await client.dashboards.filterValues();
Signature
client.dashboards.filter_values(
    *,
    property_id: str | None | NotGiven = NOT_GIVEN,
    metric_name: str | None | NotGiven = NOT_GIVEN,
    metric_type: Literal['system_metric', 'eval_metric', 'annotation_metric', 'custom_attribute', 'custom_column'] | None | NotGiven = NOT_GIVEN,
    source: Literal['traces', 'spans', 'sessions', 'users', 'voice_calls', 'prompts', 'datasets', 'dataset_column', 'simulation', 'both', 'all'] | None | NotGiven = NOT_GIVEN,
    project_ids: str | None | NotGiven = NOT_GIVEN,
    dataset_id: str | None | NotGiven = NOT_GIVEN,
    search: str | None | NotGiven = NOT_GIVEN,
    page_size: int | None | NotGiven = NOT_GIVEN,
    cursor: str | None | NotGiven = NOT_GIVEN,
    attribute_type: Literal['string', 'number', 'boolean', 'array', 'map', 'json'] | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardFilterValuesResult
client.dashboards.filterValues(params: DashboardsFilterValuesParams = {}, options?: RequestOptions): Promise<models.DashboardFilterValuesResult>

export interface DashboardsFilterValuesParams {
  /** Stable namespaced property identity returned by the metrics catalog. Legacy metric_name/metric_type remain accepted during migration. */
  property_id?: string | null;
  metric_name?: string | null;
  metric_type?: "system_metric" | "eval_metric" | "annotation_metric" | "custom_attribute" | "custom_column" | null;
  source?: "traces" | "spans" | "sessions" | "users" | "voice_calls" | "prompts" | "datasets" | "dataset_column" | "simulation" | "both" | "all" | null;
  project_ids?: string | null;
  dataset_id?: string | null;
  search?: string | null;
  page_size?: number | null;
  cursor?: string | null;
  attribute_type?: "string" | "number" | "boolean" | "array" | "map" | "json" | null;
}

Parameters

property_id string Optional

Stable namespaced property identity returned by the metrics catalog. Legacy metric_name/metric_type remain accepted during migration.

metric_name string Optional
metric_type string Optional
Allowed values:
system_metriceval_metricannotation_metriccustom_attributecustom_column
source string Optional
Allowed values:
tracesspanssessionsusersvoice_callspromptsdatasetsdataset_columnsimulationbothall
project_ids string Optional
dataset_id string Optional
search string Optional
page_size integer Optional
cursor string Optional
attribute_type string Optional
Allowed values:
stringnumberbooleanarraymapjson

Returns

DashboardFilterValuesResult.

dashboards.get

Return a dashboard and its widgets by identifier.

GET /tracer/dashboard/{id}/

MCP tool: get_dashboard

result = client.dashboards.get("your-id")
const result = await client.dashboards.get("your-id");
Signature
client.dashboards.get(
    id: str,
    *,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardDetail
client.dashboards.get(id: string, options?: RequestOptions): Promise<models.DashboardDetail>

Parameters

id string Required

Positional argument id.

Returns

DashboardDetail.

dashboards.list

List dashboards in the current workspace with their widget counts.

GET /tracer/dashboard/

MCP tool: list_dashboards

result = client.dashboards.list()
const result = await client.dashboards.list();
Signature
client.dashboards.list(
    *,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> List[models.Dashboard]
client.dashboards.list(options?: RequestOptions): Promise<Array<models.Dashboard>>

Parameters

This method takes no parameters beyond the per-call options.

Returns

A list of Dashboard.

dashboards.query

Run an ad-hoc dashboard query (time_range and metrics, with optional filters and breakdowns) and return chart data without saving a widget.

POST /tracer/dashboard/query/

MCP tool: query_dashboard_metrics

result = client.dashboards.query(time_range={"preset": "30m"}, metrics=[])
const result = await client.dashboards.query({
  time_range: { preset: "30m" },
  metrics: [],
});
Signature
client.dashboards.query(
    *,
    time_range: dict[str, Any],
    metrics: list[dict[str, Any]],
    workflow: Literal['observability', 'dataset', 'simulation'] | None | NotGiven = NOT_GIVEN,
    project_ids: list[str] | None | NotGiven = NOT_GIVEN,
    granularity: Literal['minute', 'hour', 'day', 'week', 'month'] | None | NotGiven = NOT_GIVEN,
    filters: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN,
    breakdowns: list[dict[str, Any]] | None | NotGiven = NOT_GIVEN,
    allow_sampled: bool | None | NotGiven = NOT_GIVEN,
    refresh: bool | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardQueryResult
client.dashboards.query(params: DashboardsQueryParams, options?: RequestOptions): Promise<models.DashboardQueryResult>

export interface DashboardsQueryParams {
  time_range: Record<string, unknown>;
  metrics: Array<Record<string, unknown>>;
  workflow?: "observability" | "dataset" | "simulation" | null;
  project_ids?: Array<string> | null;
  granularity?: "minute" | "hour" | "day" | "week" | "month" | null;
  filters?: Array<Record<string, unknown>> | null;
  breakdowns?: Array<Record<string, unknown>> | null;
  allow_sampled?: boolean | null;
  refresh?: boolean | null;
}

Parameters

refresh boolean Optional
time_range object Required
metrics object[] Required
workflow string Optional
Allowed values:
observabilitydatasetsimulation
project_ids string[] Optional
granularity string Optional
Allowed values:
minutehourdayweekmonth
filters object[] Optional
breakdowns object[] Optional
allow_sampled boolean Optional

Returns

DashboardQueryResult.

dashboards.update

Update the name and/or description of an existing dashboard (a partial update).

PATCH /tracer/dashboard/{id}/

MCP tool: update_dashboard

result = client.dashboards.update("your-id")
const result = await client.dashboards.update("your-id");
Signature
client.dashboards.update(
    id: str,
    *,
    name: str | None | NotGiven = NOT_GIVEN,
    description: str | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardDetail
client.dashboards.update(id: string, params: DashboardsUpdateParams = {}, options?: RequestOptions): Promise<models.DashboardDetail>

export interface DashboardsUpdateParams {
  name?: string | null;
  description?: string | null;
}

Parameters

id string Required

Positional argument id.

name string Optional
description string Optional

Returns

DashboardDetail.

client.dashboards.metrics

TypeScript: client.dashboards.metrics.

dashboards.metrics.list

List the metrics available to dashboard queries across traces, datasets, and simulations.

GET /tracer/dashboard/metrics/

MCP tool: list_dashboard_metrics

result = client.dashboards.metrics.list()
const result = await client.dashboards.metrics.list();
Signature
client.dashboards.metrics.list(
    *,
    workflow: Literal['observability', 'dataset', 'simulation'] | None | NotGiven = NOT_GIVEN,
    project_ids: str | None | NotGiven = NOT_GIVEN,
    agent_definition_id: str | None | NotGiven = NOT_GIVEN,
    per_eval_config: bool | None | NotGiven = NOT_GIVEN,
    exclude_custom_attributes: bool | None | NotGiven = NOT_GIVEN,
    search: str | None | NotGiven = NOT_GIVEN,
    category: Literal['system_metric', 'eval_metric', 'annotation_metric', 'custom_attribute', 'custom_column'] | None | NotGiven = NOT_GIVEN,
    role: Literal['metric', 'dimension'] | None | NotGiven = NOT_GIVEN,
    source: Literal['traces', 'spans', 'sessions', 'users', 'voice_calls', 'prompts', 'datasets', 'simulation', 'both', 'all'] | None | NotGiven = NOT_GIVEN,
    page: int | None | NotGiven = NOT_GIVEN,
    page_size: int | None | NotGiven = NOT_GIVEN,
    cursor_mode: bool | None | NotGiven = NOT_GIVEN,
    cursor: str | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardMetricsCatalogResult
client.dashboards.metrics.list(params: DashboardsMetricsListParams = {}, options?: RequestOptions): Promise<models.DashboardMetricsCatalogResult>

export interface DashboardsMetricsListParams {
  workflow?: "observability" | "dataset" | "simulation" | null;
  project_ids?: string | null;
  agent_definition_id?: string | null;
  per_eval_config?: boolean | null;
  exclude_custom_attributes?: boolean | null;
  search?: string | null;
  category?: "system_metric" | "eval_metric" | "annotation_metric" | "custom_attribute" | "custom_column" | null;
  role?: "metric" | "dimension" | null;
  source?: "traces" | "spans" | "sessions" | "users" | "voice_calls" | "prompts" | "datasets" | "simulation" | "both" | "all" | null;
  page?: number | null;
  page_size?: number | null;
  cursor_mode?: boolean | null;
  cursor?: string | null;
}

Parameters

workflow string Optional
Allowed values:
observabilitydatasetsimulation
project_ids string Optional
agent_definition_id string Optional
per_eval_config boolean Optional
exclude_custom_attributes boolean Optional
search string Optional
category string Optional
Allowed values:
system_metriceval_metricannotation_metriccustom_attributecustom_column
role string Optional
Allowed values:
metricdimension
source string Optional
Allowed values:
tracesspanssessionsusersvoice_callspromptsdatasetssimulationbothall
page integer Optional
page_size integer Optional
cursor_mode boolean Optional
cursor string Optional

Returns

DashboardMetricsCatalogResult.

client.dashboards.widgets

TypeScript: client.dashboards.widgets.

dashboards.widgets.create

Add a widget to a dashboard. query_config uses the query_dashboard_metrics request shape (time_range plus metrics); discover metric names with list_dashboard_metrics.

POST /tracer/dashboard/{dashboard_pk}/widgets/

MCP tool: create_dashboard_widget

result = client.dashboards.widgets.create("your-dashboard-pk")
const result = await client.dashboards.widgets.create("your-dashboard-pk");
Signature
client.dashboards.widgets.create(
    dashboard_pk: str,
    *,
    name: str | None | NotGiven = NOT_GIVEN,
    description: str | None | NotGiven = NOT_GIVEN,
    position: int | None | NotGiven = NOT_GIVEN,
    width: int | None | NotGiven = NOT_GIVEN,
    height: int | None | NotGiven = NOT_GIVEN,
    query_config: dict[str, Any] | None | NotGiven = NOT_GIVEN,
    chart_config: dict[str, Any] | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardWidget
client.dashboards.widgets.create(dashboardPk: string, params: DashboardsWidgetsCreateParams = {}, options?: RequestOptions): Promise<models.DashboardWidget>

export interface DashboardsWidgetsCreateParams {
  name?: string | null;
  description?: string | null;
  position?: number | null;
  width?: number | null;
  height?: number | null;
  query_config?: Record<string, unknown> | null;
  chart_config?: Record<string, unknown> | null;
}

Parameters

dashboard_pk string Required

Positional argument dashboard_pk.

name string Optional
description string Optional
position integer Optional
width integer Optional
height integer Optional
query_config object Optional
chart_config object Optional

Returns

DashboardWidget.

dashboards.widgets.get

Return a dashboard widget, including its query_config and chart_config.

GET /tracer/dashboard/{dashboard_pk}/widgets/{id}/

MCP tool: get_dashboard_widget

result = client.dashboards.widgets.get("your-dashboard-pk", "your-id")
const result = await client.dashboards.widgets.get("your-dashboard-pk", "your-id");
Signature
client.dashboards.widgets.get(
    dashboard_pk: str,
    id: str,
    *,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardWidget
client.dashboards.widgets.get(dashboardPk: string, id: string, options?: RequestOptions): Promise<models.DashboardWidget>

Parameters

dashboard_pk string Required

Positional argument dashboard_pk.

id string Required

Positional argument id.

Returns

DashboardWidget.

dashboards.widgets.list

List the widgets on a dashboard.

GET /tracer/dashboard/{dashboard_pk}/widgets/

Paginated: returns a pager (how pagination works) · MCP tool: list_dashboard_widgets

for item in client.dashboards.widgets.list("your-dashboard-pk"):
    print(item)
for await (const item of client.dashboards.widgets.list("your-dashboard-pk")) {
  console.log(item);
}
Signature
client.dashboards.widgets.list(
    dashboard_pk: str,
    *,
    limit: int | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> SyncPager[models.DashboardWidget]
client.dashboards.widgets.list(dashboardPk: string, params: DashboardsWidgetsListParams = {}, options?: RequestOptions): Pager<models.DashboardWidget>

export interface DashboardsWidgetsListParams {
  /** Number of results to return per page. */
  limit?: number | null;
}

Parameters

dashboard_pk string Required

Positional argument dashboard_pk.

limit integer Optional

Number of results to return per page.

The pager sends page itself; pass limit to change the page size.

Returns

A pager of DashboardWidget items: iterate it, or call to_list() (Python) / toArray() (TypeScript).

dashboards.widgets.query

Execute a saved widget’s query and return its chart data.

POST /tracer/dashboard/{dashboard_pk}/widgets/{id}/query/

MCP tool: query_dashboard_widget

result = client.dashboards.widgets.query("your-dashboard-pk", "your-id")
const result = await client.dashboards.widgets.query("your-dashboard-pk", "your-id");
Signature
client.dashboards.widgets.query(
    dashboard_pk: str,
    id: str,
    *,
    allow_sampled: bool | None | NotGiven = NOT_GIVEN,
    refresh: bool | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardQueryResult
client.dashboards.widgets.query(dashboardPk: string, id: string, params: DashboardsWidgetsQueryParams = {}, options?: RequestOptions): Promise<models.DashboardQueryResult>

export interface DashboardsWidgetsQueryParams {
  allow_sampled?: boolean | null;
  refresh?: boolean | null;
}

Parameters

dashboard_pk string Required

Positional argument dashboard_pk.

id string Required

Positional argument id.

refresh boolean Optional
allow_sampled boolean Optional

Returns

DashboardQueryResult.

dashboards.widgets.update

Update selected fields on a dashboard widget, such as its query_config, chart_config, or layout.

PATCH /tracer/dashboard/{dashboard_pk}/widgets/{id}/

MCP tool: update_dashboard_widget

result = client.dashboards.widgets.update("your-dashboard-pk", "your-id")
const result = await client.dashboards.widgets.update("your-dashboard-pk", "your-id");
Signature
client.dashboards.widgets.update(
    dashboard_pk: str,
    id: str,
    *,
    name: str | None | NotGiven = NOT_GIVEN,
    description: str | None | NotGiven = NOT_GIVEN,
    position: int | None | NotGiven = NOT_GIVEN,
    width: int | None | NotGiven = NOT_GIVEN,
    height: int | None | NotGiven = NOT_GIVEN,
    query_config: dict[str, Any] | None | NotGiven = NOT_GIVEN,
    chart_config: dict[str, Any] | None | NotGiven = NOT_GIVEN,
    extra_query: dict[str, Any] | None = None,
    extra_body: dict[str, Any] | None = None,
    options: RequestOptions | None = None,
) -> models.DashboardWidget
client.dashboards.widgets.update(dashboardPk: string, id: string, params: DashboardsWidgetsUpdateParams = {}, options?: RequestOptions): Promise<models.DashboardWidget>

export interface DashboardsWidgetsUpdateParams {
  name?: string | null;
  description?: string | null;
  position?: number | null;
  width?: number | null;
  height?: number | null;
  query_config?: Record<string, unknown> | null;
  chart_config?: Record<string, unknown> | null;
}

Parameters

dashboard_pk string Required

Positional argument dashboard_pk.

id string Required

Positional argument id.

name string Optional
description string Optional
position integer Optional
width integer Optional
height integer Optional
query_config object Optional
chart_config object Optional

Returns

DashboardWidget.

Was this page helpful?

Questions & Discussion