---
title: "POST /tracer/dashboard/{dashboard_pk}/widgets/{id}/query/"
method: POST
path: "/tracer/dashboard/{dashboard_pk}/widgets/{id}/query/"
tags: ["tracer"]
---

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

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

## Request

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

Execute the widget's query_config against ClickHouse and return results.

## Query parameters

- `refresh` boolean

## Request body

- DashboardSampleOptIn
  - `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)