---
title: "Queries an integration"
method: POST
path: "/v1/query"
tags: ["v1", "Query"]
---

# Queries an integration

`POST /v1/query`

## Query parameters

- `raw` boolean — Whether to return raw data
- `format` 'json' | 'arrow' — Response format: 'json' (default) or 'arrow'

## Request body

- ApiQueryRequest
  - `sql` string — SQL query to execute
  - `cube_query` ExtendedV1LoadRequestQuery
    - `measures` string[], nullable — List of measures to be queried.
    - `dimensions` string[], nullable — List of dimensions to be queried.
    - `segments` union — List of segments to be used in the query. A segment is a named filter defined in the data model.
      - string[]
      - object[]
    - `timeDimensions` ExtendedV1LoadRequestQueryTimeDimension[], nullable — List of time dimensions to be used in the query.
      - `dimension` string, required — The name of the time dimension.
      - `granularity` 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year', nullable — Granularity level for the time dimension. Setting this to null will filter by the specified time dimension without grouping.
      - `dateRange` union — An array of dates with the following format YYYY-MM-DD or in YYYY-MM-DDTHH:mm:ss.SSS format. Values should always be local and in query timezone. Dates in YYYY-MM-DD format are also accepted. Such dates are padded to the start and end of the day if used in start and end of date range interval accordingly.
        - string
        - string[]
      - `compareDateRange` string[], nullable — List of date ranges for period-over-period comparison. Mutually exclusive with dateRange.
    - `order` array[], nullable — Ordering criteria for query
      - unknown[]
        - unknown
    - `limit` integer, nullable — Maximum number of rows to return in the query result.
    - `offset` integer, nullable — Number of initial rows to skip in the query result. Default is 0.
    - `filters` union[], nullable — List of filters to apply to the query.
      - union
        - V1LoadRequestQueryFilterBase
          - `member` string, nullable — Dimension or measure to be used in the filter, e.g., `stories.isDraft`. Differentiates between filtering dimensions and filtering measures.
          - `operator` 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'notStartsWith' | 'endsWith' | 'notEndsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'set' | 'notSet' | 'inDateRange' | 'notInDateRange' | 'beforeDate' | 'afterDate' | 'measureFilter', nullable — Operator to apply in the filter. Some operators are exclusive to measures, while others depend on the dimension type.
          - `values` string[], nullable — List of values for the filter, provided as strings. For dates, use the `YYYY-MM-DD` format.
        - V1LoadRequestQueryFilterLogicalOr
          - `or` union[], nullable — List of filter items combined with logical OR
            - union
              - …
        - V1LoadRequestQueryFilterLogicalAnd
          - `and` union[], nullable — List of filter items combined with logical AND
            - union
              - …
    - `timezone` string, nullable — Time zone to be used for the query, specified in the TZ Database Name format (e.g., `America/Los_Angeles`).
    - `renewQuery` boolean, nullable — Cube will renew all refreshKey for queries and query results in the foreground. However, if the refreshKey (or refreshKey.every) doesn't indicate that there's a need for an update this setting has no effect. The default value is false
    - `ungrouped` boolean, nullable — If set to true, Cube will run an ungrouped query.
    - `forceNoCache` boolean, nullable
  - `integration_id` string — Optional integration ID to execute query on
  - `log_event` boolean — Flag enabling or disabling event logging for the request
  - `persist` boolean — Whether to cache sql query result
  - `invalidate` boolean — Invalidates sql query result
  - `raw` boolean — Whether to return raw data
  - `resources` ComputeResourceRequest — Compute resource request shared by the DuckDB cluster and E2B sandbox paths. Defaults are sized for the DuckDB cluster. Non-DuckDB callers must check `model_fields_set` before reading `cpu`/`memory`, otherwise the DuckDB defaults will be used for other engines — see `defapi.config.e2b.select_e2b_sandbox_tier` for an example.
    - `cpu` string — CPU cores in Kubernetes format (e.g., '4', '2.5', '500m')
    - `memory` string — Memory in Kubernetes format (e.g., '16Gi', '512Mi', '1G')
    - `timeoutSeconds` integer — Job timeout in seconds (60-604800, default 3600)

## Response `200`

Success

- ApiQueryResponse
  - `data` unknown[] — Output data.
    - unknown
  - `raw_data` unknown
  - `schema` BlockResultsRowSchema[] — Schema of rows.
    - `name` string, required
    - `type` string, required
    - `sql_value_type` string, nullable
    - `format` string, nullable
    - `meta` object, nullable
  - `integration_id` union, required
    - string, uuid
    - string
  - `executed_query` union — The SQL or Cube query that was executed (for debugging/display)
    - string
    - object
  - `query_type` string, nullable — Type of query executed: 'sql' or 'cube'

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/definite/apis/defapi.md) · [All operations](https://skmtc.dev/definite/apis/defapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/definite/defapi/revisions/3943d8deb3be/schema)