---
title: "Execute a widget query and return chart data."
method: POST
path: "/tracer/dashboard/query/"
tags: ["tracer"]
---

# Execute a widget query and return chart data.

`POST /tracer/dashboard/query/`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/tracer/dashboard/query/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in header `X-Secret-Key`

Each metric carries a ``source`` field ("traces" or "datasets").
Metrics are partitioned by source and dispatched to the appropriate
query builder.  Results are merged into a single response.

Each metric is validated against the canonical query contract before
it reaches any query builder.

## Query parameters

- `refresh` boolean

## Request body

- DashboardQuery
  - `workflow` 'observability' | 'dataset' | 'simulation'
  - `project_ids` string[]
  - `time_range` DashboardTimeRange, required
    - `preset` '30m' | '6h' | 'today' | 'yesterday' | '7D' | '30D' | '3M' | '6M' | '12M'
    - `custom_start` string, date-time
    - `custom_end` string, date-time
  - `granularity` 'minute' | 'hour' | 'day' | 'week' | 'month'
  - `metrics` DashboardMetric[], required
    - `id` string
    - `name` string, required
    - `property_id` string
    - `display_name` string
    - `type` 'system_metric' | 'eval_metric' | 'annotation_metric' | 'custom_attribute' | 'custom_column', required
    - `source` 'traces' | 'datasets' | 'simulation' | 'both' | 'all'
    - `aggregation` 'avg' | 'median' | 'max' | 'min' | 'p25' | 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | 'count' | 'count_distinct' | 'sum' | 'pass_rate' | 'fail_rate' | 'pass_count' | 'fail_count' | 'true_rate'
    - `unit` string
    - `output_type` string
    - `eval_key` string
    - `config_id` string
    - `label_id` string
    - `attribute_key` string
    - `attribute_type` 'string' | 'text' | 'number' | 'float' | 'integer' | 'boolean' | 'datetime' | 'date'
    - `column_id` string
    - `data_type` 'string' | 'text' | 'number' | 'float' | 'integer' | 'boolean' | 'datetime' | 'date'
    - `filters` object[]
      - `column_id` string, required: Column or attribute id to filter on.
      - `property_id` string: Optional stable namespaced Property Registry identity.
      - `display_name` string: Optional UI label for chips and saved views.
      - `source` string: Optional source surface for mixed-source filters, for example traces, datasets, or simulation.
      - `output_type` string: Optional metric output type metadata used by eval and annotation filters.
      - `filter_config` object, required
        - `filter_type` string, required: Canonical field type, for example text, number, boolean, datetime, categorical, thumbs, annotator, array, or map. Legacy json is value-sensitive for SPAN_ATTRIBUTE filters: list values become array and object values become map.
        - `filter_op` string, required: Canonical operator from api_contracts/filter_contract.json, for example equals, not_equals, in, not_in, between, not_between, is_null, or is_not_null.
        - `filter_value` unknown
        - `col_type` string: Column family such as SYSTEM_METRIC, SPAN_ATTRIBUTE, EVAL_METRIC, ANNOTATION, or NORMAL.
        - `attribute_value_types` string[]: Optional storage-family provenance aligned one-for-one with filter_value for mixed SPAN_ATTRIBUTE in/not_in filters. Null entries retain filter_type semantics for manually entered values.
  - `filters` object[]
    - `column_id` string, required: Column or attribute id to filter on.
    - `property_id` string: Optional stable namespaced Property Registry identity.
    - `display_name` string: Optional UI label for chips and saved views.
    - `source` string: Optional source surface for mixed-source filters, for example traces, datasets, or simulation.
    - `output_type` string: Optional metric output type metadata used by eval and annotation filters.
    - `filter_config` object, required
      - `filter_type` string, required: Canonical field type, for example text, number, boolean, datetime, categorical, thumbs, annotator, array, or map. Legacy json is value-sensitive for SPAN_ATTRIBUTE filters: list values become array and object values become map.
      - `filter_op` string, required: Canonical operator from api_contracts/filter_contract.json, for example equals, not_equals, in, not_in, between, not_between, is_null, or is_not_null.
      - `filter_value` unknown
      - `col_type` string: Column family such as SYSTEM_METRIC, SPAN_ATTRIBUTE, EVAL_METRIC, ANNOTATION, or NORMAL.
      - `attribute_value_types` string[]: Optional storage-family provenance aligned one-for-one with filter_value for mixed SPAN_ATTRIBUTE in/not_in filters. Null entries retain filter_type semantics for manually entered values.
  - `breakdowns` DashboardBreakdown[]
    - `name` string, required
    - `property_id` string
    - `display_name` string
    - `type` 'system_metric' | 'eval_metric' | 'annotation_metric' | 'custom_attribute' | 'custom_column'
    - `source` 'traces' | 'datasets' | 'simulation' | 'both' | 'all'
    - `output_type` string
    - `label_id` string
    - `config_id` string
    - `eval_key` string
    - `attribute_key` string
    - `attribute_type` 'string' | 'text' | 'number' | 'float' | 'integer' | 'boolean' | 'datetime' | 'date'
    - `column_id` string
    - `data_type` 'string' | 'text' | 'number' | 'float' | 'integer' | 'boolean' | 'datetime' | 'date'
  - `allow_sampled` boolean: Deprecated compatibility parameter; accepted but ignored. The response explicitly labels exact, rollup, or unavailable provenance.

## Response `200`

OK

- DashboardQueryApiResponse
  - `status` boolean
  - `result` DashboardQueryResult, required
    - `metrics` DashboardQueryMetricResult[], required
      - `id` string, required
      - `name` string, required
      - `aggregation` 'avg' | 'median' | 'max' | 'min' | 'p25' | 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | 'count' | 'count_distinct' | 'sum' | 'pass_rate' | 'fail_rate' | 'pass_count' | 'fail_count' | 'true_rate', required
      - `unit` string, required
      - `series` DashboardQuerySeries[], required
        - `name` string, required
        - `data` DashboardQuerySeriesPoint[], required
          - `timestamp` string, required
          - `value` number, nullable, required
      - `series_total` integer
      - `series_truncated` boolean
      - `query_complete` boolean
      - `query_sampled` boolean
      - `query_status` 'complete' | 'degraded'
      - `query_error_code` 'sample_limit' | 'read_budget_exceeded' | 'query_failed' | 'bounded_shape_unavailable' | 'invalid_window' | 'malformed_result'
      - `query_exact` boolean
      - `query_provenance` 'exact_snapshot' | 'materialized_rollup' | 'authorized_empty_scope' | 'bounded_unavailable'
      - `query_sampling_strategy` string
      - `query_sampling_interval_seconds` integer
      - `query_sample_limit` integer
      - `query_sample_per_bucket` integer
    - `time_range` DashboardQueryTimeRangeResult, required
      - `start` string, required
      - `end` string, required
    - `granularity` 'minute' | 'hour' | 'day' | 'week' | 'month', required
    - `query_complete` boolean
    - `query_status` 'complete' | 'degraded' | 'pending'
    - `query_sampled` boolean
    - `query_exact` boolean
    - `query_provenance` 'exact_snapshot' | 'materialized_rollup' | 'authorized_empty_scope' | 'bounded_unavailable'
    - `query_error_code` 'sample_limit' | 'read_budget_exceeded' | 'query_failed' | 'bounded_shape_unavailable' | 'invalid_window' | 'malformed_result'
    - `query_sampling_strategy` string
    - `query_count` integer
    - `query_rows_returned` integer
    - `query_elapsed_ms` number
    - `query_completed_at` string, date-time
    - `query_cached` boolean
    - `query_refresh_failed` boolean
    - `query_refreshing` boolean
    - `query_snapshot_version_ceiling` integer
    - `query_snapshot_capture_count` integer
    - `query_snapshot_relation_count` integer

## Other responses

- `400`: Bad Request
- `500`: Internal Server Error
- `503`: Service Unavailable
- `default`: Default error response

---

[API](https://skmtc.dev/futureagi/apis/future-agi-management-api.md) · [All operations](https://skmtc.dev/futureagi/apis/future-agi-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/futureagi/apis/future-agi-management-api/revisions/c8684118e142?raw)