> ## Documentation Index > Fetch the complete documentation index at: https://traceroot.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Run Widget Query > Run a widget spec for a window and return its rows with the window answered. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/public/widgets/query openapi: 3.1.0 info: title: TraceRoot Public API version: 0.1.0 servers: - description: TraceRoot Cloud url: https://app.traceroot.ai - description: Self-hosted url: '{baseUrl}' variables: baseUrl: default: http://localhost:8000 description: Your TraceRoot backend URL security: [] paths: /api/v1/public/widgets/query: post: tags: - Widgets summary: Run Widget Query description: >- Run a widget spec for a window and return its rows with the window answered. operationId: run_widget_query parameters: - description: >- Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project. in: query name: project_id required: false schema: anyOf: - type: string - type: 'null' description: >- Target project for the request. Required when authenticating with a user session token (a user credential is only meaningful scoped to a project); for an API key it is optional and, if given, must match the key's project. title: Project Id requestBody: content: application/json: schema: $ref: '#/components/schemas/WidgetQueryRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/WidgetQueryResponse' description: Successful Response '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication failed '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication service unavailable security: - BearerAuth: [] components: schemas: WidgetQueryRequest: additionalProperties: false description: |- Envelope that pairs a WidgetSpec with the time window to answer it for. The window is either a ``range`` preset (the site picker's ids — how the agent and the CLI describe one) or explicit ``start_time``/``end_time`` (how the dashboard page and the card previews do). Neither means the site's default window; both, or one bound alone, is rejected. The rules live in ``rest.services.date_presets.resolve_window`` so every query surface applies the same ones. properties: bucket_seconds: anyOf: - maximum: 86400 minimum: 1 type: integer - type: 'null' title: Bucket Seconds end_time: anyOf: - format: date-time type: string - type: 'null' title: End Time range: anyOf: - enum: - 30m - 1h - 3h - 6h - 1d - 7d - 14d - 30d - 60d - 90d type: string - type: 'null' description: >- A preset window ending now, by the site picker's id. Give this or explicit start_time/end_time; neither means the site's 24-hour default. title: Range spec: $ref: '#/components/schemas/WidgetSpec' start_time: anyOf: - format: date-time type: string - type: 'null' title: Start Time required: - spec title: WidgetQueryRequest type: object WidgetQueryResponse: description: >- Query result returned to the frontend; meta carries display hints (e.g. granularity for time-series displays). properties: columns: items: type: string title: Columns type: array meta: additionalProperties: true title: Meta type: object rows: items: items: {} type: array title: Rows type: array window: $ref: '#/components/schemas/QueryWindow' required: - columns - rows - window title: WidgetQueryResponse type: object ErrorResponse: description: >- The canonical public error envelope (matches the gateway's normalized shape). properties: detail: title: Detail type: string required: - detail title: ErrorResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object WidgetSpec: additionalProperties: false description: |- Full declarative specification of a single dashboard widget. Mirrors the canonical zod ``WidgetSpecSchema`` (frontend/ui/src/features/dashboards/types.ts); the frontend widget-spec-parity test guards the two against structural drift. properties: breakdown: anyOf: - type: string - type: 'null' title: Breakdown display: $ref: '#/components/schemas/WidgetDisplay' filters: items: $ref: '#/components/schemas/WidgetFilter' title: Filters type: array metric: $ref: '#/components/schemas/WidgetMetric' view: enum: - spans - traces title: View type: string required: - view - metric - display title: WidgetSpec type: object QueryWindow: description: |- The window a query was actually answered for. ``range`` is the preset id the caller gave (or the default's, when they gave nothing) and None for explicit bounds. ``clamped`` is True when the plan's retention pulled ``start_time`` forward — the honest reason a caller's window and the answered one differ. properties: clamped: title: Clamped type: boolean end_time: format: date-time title: End Time type: string range: anyOf: - enum: - 30m - 1h - 3h - 6h - 1d - 7d - 14d - 30d - 60d - 90d type: string - type: 'null' title: Range start_time: format: date-time title: Start Time type: string required: - start_time - end_time - range - clamped title: QueryWindow type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object WidgetDisplay: additionalProperties: false description: Controls how the query result is rendered on the dashboard. properties: type: enum: - line - area - bar - pie - number - table - histogram title: Type type: string required: - type title: WidgetDisplay type: object WidgetFilter: additionalProperties: false description: A single filter predicate applied to a widget query. properties: field: title: Field type: string key: title: Key type: string op: enum: - '=' - contains - in - '>' - '>=' - < - <= title: Op type: string value: anyOf: - minLength: 1 type: string - type: number - items: minLength: 1 type: string maxItems: 100 minItems: 1 type: array title: Value type: - string - number - array required: - field - op - value title: WidgetFilter type: object WidgetMetric: additionalProperties: false description: The measure and aggregation function that define the widget's y-axis. properties: agg: enum: - count - sum - avg - min - max - p50 - p75 - p90 - p95 - p99 - uniq title: Agg type: string measure: title: Measure type: string required: - measure - agg title: WidgetMetric type: object securitySchemes: BearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.