> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chartbrew.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query dataset data

> Read dataset data with variables, field filters, or a source refresh.

Use this route for runtime variables, field filters, a timezone, or `refresh: true`. Filters run
after joins and dataset transformations.

Variables and source refreshes require the **Refresh data from sources** key permission.


## OpenAPI

````yaml POST /api/v1/teams/{team_id}/datasets/{dataset_id}/data
openapi: 3.0.1
info:
  title: Chartbrew API reference
  description: The OpenAPI specification for Chartbrew
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.chartbrew.com
security:
  - bearerAuth: []
paths:
  /api/v1/teams/{team_id}/datasets/{dataset_id}/data:
    post:
      tags:
        - Data API
      summary: Query dataset data
      description: >-
        Returns dataset data with runtime variables, field filters, an IANA
        timezone, or an explicit source refresh. Variables and source refreshes
        require data refresh permission.
      operationId: queryDatasetDataV1
      parameters:
        - name: team_id
          in: path
          required: true
          description: Positive team ID bound to the API key.
          schema:
            type: integer
            minimum: 1
        - name: dataset_id
          in: path
          required: true
          description: Positive dataset ID.
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetDataRequest'
            example:
              variables:
                region: APAC
              filters:
                - type: field
                  field: root[].amount
                  operator: greaterOrEqual
                  value: 100
              refresh: false
              timezone: Asia/Bangkok
      responses:
        '200':
          $ref: '#/components/responses/DatasetDataSuccess'
        '400':
          $ref: '#/components/responses/DataApiInvalidRequest'
        '401':
          $ref: '#/components/responses/DataApiUnauthorized'
        '403':
          $ref: '#/components/responses/DataApiForbidden'
        '404':
          $ref: '#/components/responses/DataApiNotFound'
        '406':
          $ref: '#/components/responses/DataApiNotAcceptable'
        '413':
          $ref: '#/components/responses/DataApiTooLarge'
        '415':
          $ref: '#/components/responses/DataApiUnsupportedMediaType'
        '429':
          $ref: '#/components/responses/DataApiRateLimited'
        '500':
          $ref: '#/components/responses/DataApiInternalError'
        '503':
          $ref: '#/components/responses/DataApiUnavailable'
        '504':
          $ref: '#/components/responses/DataApiTimeout'
      security:
        - dataApiBearer: []
components:
  schemas:
    DatasetDataRequest:
      type: object
      additionalProperties: false
      properties:
        variables:
          $ref: '#/components/schemas/DataApiVariables'
        filters:
          type: array
          maxItems: 50
          description: >-
            Chart-wide field filters. Date and chart dataset configuration
            scopes are not accepted.
          items:
            $ref: '#/components/schemas/DataApiFieldFilter'
          default: []
        refresh:
          type: boolean
          default: false
        timezone:
          type: string
          description: IANA timezone used for dataset field comparisons.
          default: UTC
          example: Asia/Bangkok
    DataApiVariables:
      type: object
      description: >-
        Runtime variable values. The default limit is 100 keys, 10 nested
        levels, and 8192 bytes per string. Variable names __proto__,
        constructor, and prototype are not accepted.
      maxProperties: 100
      additionalProperties: {}
    DataApiFieldFilter:
      type: object
      additionalProperties: false
      required:
        - field
        - operator
      properties:
        type:
          type: string
          enum:
            - field
          default: field
        field:
          type: string
          minLength: 1
          description: >-
            Dataset field path, such as root[].status. Dataset filters must
            identify one array collection.
        operator:
          type: string
          enum:
            - is
            - isNot
            - contains
            - notContains
            - greaterThan
            - greaterOrEqual
            - lessThan
            - lessOrEqual
            - isNull
            - isNotNull
        value:
          description: JSON comparison value. It is optional for isNull and isNotNull.
          nullable: true
        scope:
          type: string
          enum:
            - chart
            - cdc
        cdcId:
          description: Chart dataset configuration ID. Use only with chart cdc scope.
          oneOf:
            - type: integer
              minimum: 1
            - type: string
              pattern: ^[1-9]\d*$
        forceSourceRefresh:
          type: boolean
          default: false
    DatasetData:
      type: object
      required:
        - version
        - generatedAt
        - resource
        - fields
        - data
      properties:
        version:
          type: integer
          enum:
            - 1
        generatedAt:
          type: string
          format: date-time
        resource:
          $ref: '#/components/schemas/DataApiResource'
        fields:
          type: array
          items:
            $ref: '#/components/schemas/DatasetDataField'
        data:
          description: >-
            Joined and transformed dataset value. It can be an array, object,
            scalar, or null.
          nullable: true
    DataApiError:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/DataApiErrorDetail'
    DataApiResource:
      type: object
      required:
        - kind
        - id
      properties:
        kind:
          type: string
          enum:
            - chart
            - dataset
        id:
          type: integer
        name:
          type: string
          nullable: true
    DatasetDataField:
      type: object
      required:
        - key
        - type
      properties:
        key:
          type: string
          example: root[].amount
        type:
          type: string
          enum:
            - number
            - date
            - string
            - boolean
            - array
            - object
            - unknown
    DataApiErrorDetail:
      type: object
      required:
        - code
        - message
        - requestId
      properties:
        code:
          type: string
          enum:
            - INVALID_REQUEST
            - INVALID_VARIABLE
            - INVALID_FILTER
            - API_KEY_REQUIRED
            - API_KEY_INVALID
            - API_KEY_SCOPE_REQUIRED
            - RESOURCE_NOT_FOUND
            - NOT_ACCEPTABLE
            - REQUEST_TOO_LARGE
            - RESPONSE_TOO_LARGE
            - UNSUPPORTED_MEDIA_TYPE
            - RATE_LIMITED
            - INTERNAL_ERROR
            - DATA_UNAVAILABLE
            - EXECUTION_TIMEOUT
        message:
          type: string
        requestId:
          type: string
          format: uuid
  responses:
    DatasetDataSuccess:
      description: Joined and transformed dataset data.
      headers:
        ETag:
          $ref: '#/components/headers/DataEtag'
        Last-Modified:
          $ref: '#/components/headers/DataLastModified'
        X-Chartbrew-Data-Stale:
          $ref: '#/components/headers/DataStale'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DatasetData'
          example:
            version: 1
            generatedAt: '2026-08-25T08:00:00.000Z'
            resource:
              kind: dataset
              id: 18
              name: Orders
            fields:
              - key: root[].amount
                type: number
              - key: root[].customer.name
                type: string
            data:
              - amount: 120
                customer:
                  name: Ada
    DataApiInvalidRequest:
      description: The ID, body, variable, filter, or JSON shape is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
          example:
            error:
              code: INVALID_FILTER
              message: One or more filters are not valid.
              requestId: 7a39da10-819c-4db4-9dcf-f27d48e3a7c0
    DataApiUnauthorized:
      description: The Data API bearer key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
          example:
            error:
              code: API_KEY_INVALID
              message: The API key is not valid.
              requestId: 7a39da10-819c-4db4-9dcf-f27d48e3a7c0
    DataApiForbidden:
      description: The key does not have read or refresh permission.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
          example:
            error:
              code: API_KEY_SCOPE_REQUIRED
              message: The API key does not have the required permission.
              requestId: 7a39da10-819c-4db4-9dcf-f27d48e3a7c0
    DataApiNotFound:
      description: The resource is missing, outside key access, or under another parent.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              requestId: 7a39da10-819c-4db4-9dcf-f27d48e3a7c0
    DataApiNotAcceptable:
      description: The client does not accept JSON.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
    DataApiTooLarge:
      description: >-
        The request exceeds 65536 bytes by default, or the complete response
        exceeds 5242880 bytes by default.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
    DataApiUnsupportedMediaType:
      description: The POST body is not application/json.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
    DataApiRateLimited:
      description: >-
        The default limit is 60 requests per API key per minute or 30 failed
        authentication attempts per IP per minute.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
          example:
            error:
              code: RATE_LIMITED
              message: Too many requests were sent. Try again later.
              requestId: 7a39da10-819c-4db4-9dcf-f27d48e3a7c0
    DataApiInternalError:
      description: The server could not complete the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
    DataApiUnavailable:
      description: No saved result is usable and the source cannot supply data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
    DataApiTimeout:
      description: The request exceeded the default 30000 millisecond execution limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataApiError'
  headers:
    DataEtag:
      description: >-
        Content identity returned for GET responses. Generation time is not part
        of this value.
      schema:
        type: string
        example: '"pd-v1-0123456789abcdef"'
    DataLastModified:
      description: Generation time in HTTP date format.
      schema:
        type: string
        example: Tue, 25 Aug 2026 08:00:00 GMT
    DataStale:
      description: >-
        True when Chartbrew returns the last known result while source data is
        stale.
      schema:
        type: boolean
        example: false
    RetryAfter:
      description: Seconds to wait before another request.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    dataApiBearer:
      type: http
      scheme: bearer
      bearerFormat: Chartbrew API key
      description: >-
        A database-bound Data API key created in Team settings. Session and
        share tokens are not accepted.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.