---
title: "Execute Query"
method: POST
path: "/analytics/widgets/execute-query"
tags: ["provider", "analytics", "analytics"]
---

# Execute Query

`POST /analytics/widgets/execute-query`

Execute a dynamic analytics query.

## Headers

- `TENANT` string, required
- `API-KEY` string, required

## Request body

- QueryExecutionSchema — Schema for executing a query.
  - `page` integer, nullable
  - `perPage` integer, nullable
  - `sortBy` string, nullable
  - `sortDirection` 'asc' | 'desc', nullable
  - `locationId` string, nullable
  - `queryConfig` QueryConfigSchema, required — Schema for query configuration.
    - `table` string, required — Table name to query
    - `fields` string[], required — List of fields to select
    - `filters` object[], nullable — Optional filters to apply
    - `aggregations` object, nullable — Optional aggregations to apply
    - `groupBy` string[], nullable — Optional fields to group by
    - `temporalGrouping` object, nullable — Optional temporal grouping for date fields
    - `orderBy` object, nullable — Optional ordering configuration
  - `chartType` string, nullable — Chart type to optimize query behavior (table, bar, etc.)
  - `search` string, nullable — Global search term to filter across text fields
  - `tz` string, required — Timezone for date filtering and temporal grouping

## Response `200`

Successful Response

- QueryResultSchema — Schema for query execution results.
  - `data` object[], required — Query result data
  - `totalCount` integer, required — Total number of results
  - `executionTimeMs` number, required — Query execution time in milliseconds
  - `metadata` object, nullable — Field metadata for chart rendering

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/decodahealth/apis/decoda-api.md) · [All operations](https://skmtc.dev/decodahealth/apis/decoda-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/decodahealth/decoda-api/revisions/4939a65a89d2/schema)