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
| Method | Description |
|---|---|
dashboards.create | Create an empty dashboard in the current workspace; add widgets with create_dashboard_widget. |
dashboards.delete | Delete a dashboard and the widgets on it. |
dashboards.filter_values | List the distinct values of a metric or attribute for use in dashboard filters. |
dashboards.get | Return a dashboard and its widgets by identifier. |
dashboards.list | List dashboards in the current workspace with their widget counts. |
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. |
dashboards.update | Update the name and/or description of an existing dashboard (a partial update). |
dashboards.metrics.list | List the metrics available to dashboard queries across traces, datasets, and simulations. |
dashboards.widgets.create | Add a widget to a dashboard. |
dashboards.widgets.get | Return a dashboard widget, including its query_config and chart_config. |
dashboards.widgets.list | List the widgets on a dashboard. |
dashboards.widgets.query | Execute a saved widget’s query and return its chart data. |
dashboards.widgets.update | Update 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.
/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.DashboardDetailclient.dashboards.create(params: DashboardsCreateParams, options?: RequestOptions): Promise<models.DashboardDetail>
export interface DashboardsCreateParams {
name: string;
description?: string | null;
} Parameters
Returns
dashboards.delete
Delete a dashboard and the widgets on it. This is the only way to remove a dashboard created earlier.
/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,
) -> Anyclient.dashboards.delete(id: string, options?: RequestOptions): Promise<unknown> Parameters
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.
/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.DashboardFilterValuesResultclient.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
Stable namespaced property identity returned by the metrics catalog. Legacy metric_name/metric_type remain accepted during migration.
system_metriceval_metricannotation_metriccustom_attributecustom_column tracesspanssessionsusersvoice_callspromptsdatasetsdataset_columnsimulationbothall stringnumberbooleanarraymapjson Returns
dashboards.get
Return a dashboard and its widgets by identifier.
/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.DashboardDetailclient.dashboards.get(id: string, options?: RequestOptions): Promise<models.DashboardDetail> Parameters
Positional argument id.
Returns
dashboards.list
List dashboards in the current workspace with their widget counts.
/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.
/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.DashboardQueryResultclient.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
observabilitydatasetsimulation minutehourdayweekmonth Returns
dashboards.update
Update the name and/or description of an existing dashboard (a partial update).
/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.DashboardDetailclient.dashboards.update(id: string, params: DashboardsUpdateParams = {}, options?: RequestOptions): Promise<models.DashboardDetail>
export interface DashboardsUpdateParams {
name?: string | null;
description?: string | null;
} Parameters
Positional argument id.
Returns
client.dashboards.metrics
TypeScript: client.dashboards.metrics.
dashboards.metrics.list
List the metrics available to dashboard queries across traces, datasets, and simulations.
/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.DashboardMetricsCatalogResultclient.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
observabilitydatasetsimulation system_metriceval_metricannotation_metriccustom_attributecustom_column metricdimension tracesspanssessionsusersvoice_callspromptsdatasetssimulationbothall 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.
/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.DashboardWidgetclient.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
Positional argument dashboard_pk.
Returns
dashboards.widgets.get
Return a dashboard widget, including its query_config and chart_config.
/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.DashboardWidgetclient.dashboards.widgets.get(dashboardPk: string, id: string, options?: RequestOptions): Promise<models.DashboardWidget> Parameters
Positional argument dashboard_pk.
Positional argument id.
Returns
dashboards.widgets.list
List the widgets on a dashboard.
/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
Positional argument dashboard_pk.
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.
/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.DashboardQueryResultclient.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
Positional argument dashboard_pk.
Positional argument id.
Returns
dashboards.widgets.update
Update selected fields on a dashboard widget, such as its query_config, chart_config, or layout.
/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.DashboardWidgetclient.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
Positional argument dashboard_pk.
Positional argument id.
Returns
Questions & Discussion