Observe Dataset Query Filter API

openapi: 3.2.0
info:
  title: Observeinc Dataset Query Filter API
  version: 1.0.230307
  x-assembled-from:
  - https://docs.observeinc.com/reference/createapitoken.md
  - https://docs.observeinc.com/reference/createdashboard.md
  - https://docs.observeinc.com/reference/createdatasetqueryfilter.md
  - https://docs.observeinc.com/reference/createingestfilter.md
  - https://docs.observeinc.com/reference/createingestroute.md
  - https://docs.observeinc.com/reference/createingesttoken.md
  - https://docs.observeinc.com/reference/createmonitor.md
  - https://docs.observeinc.com/reference/createmonitormute.md
  - https://docs.observeinc.com/reference/createmonitormuterule.md
  - https://docs.observeinc.com/reference/createreferencetable.md
  - https://docs.observeinc.com/reference/createserviceaccount.md
  - https://docs.observeinc.com/reference/createskill.md
  - https://docs.observeinc.com/reference/deleteapitoken.md
  - https://docs.observeinc.com/reference/deletedashboard.md
  - https://docs.observeinc.com/reference/deletedatasetqueryfilter.md
  - https://docs.observeinc.com/reference/deleteingestfilter.md
  - https://docs.observeinc.com/reference/deleteingestroute.md
  - https://docs.observeinc.com/reference/deleteingesttoken.md
  - https://docs.observeinc.com/reference/deletemonitor.md
  - https://docs.observeinc.com/reference/deletemonitormute.md
  - https://docs.observeinc.com/reference/deletemonitormuterule.md
  - https://docs.observeinc.com/reference/deletereferencetable.md
  - https://docs.observeinc.com/reference/deleteserviceaccount.md
  - https://docs.observeinc.com/reference/deleteskill.md
  - https://docs.observeinc.com/reference/exportquery.md
  - https://docs.observeinc.com/reference/exportquerypage.md
  - https://docs.observeinc.com/reference/exportworksheet.md
  - https://docs.observeinc.com/reference/generateapitoken.md
  - https://docs.observeinc.com/reference/getalert.md
  - https://docs.observeinc.com/reference/getapitoken.md
  - https://docs.observeinc.com/reference/getapminvocationgraph.md
  - https://docs.observeinc.com/reference/getdashboard.md
  - https://docs.observeinc.com/reference/getdataset.md
  - https://docs.observeinc.com/reference/getdatasetbyid.md
  - https://docs.observeinc.com/reference/getdatasetgraph.md
  - https://docs.observeinc.com/reference/getdatasetqueryfilterbyid.md
  - https://docs.observeinc.com/reference/getdatasetstats.md
  - https://docs.observeinc.com/reference/getingestfilter.md
  - https://docs.observeinc.com/reference/getingestroute.md
  - https://docs.observeinc.com/reference/getingesttoken.md
  - https://docs.observeinc.com/reference/getmonitor-1.md
  - https://docs.observeinc.com/reference/getmonitormute.md
  - https://docs.observeinc.com/reference/getmonitormuterule.md
  - https://docs.observeinc.com/reference/getmonitorstats.md
  - https://docs.observeinc.com/reference/getreferencetable.md
  - https://docs.observeinc.com/reference/getserviceaccount.md
  - https://docs.observeinc.com/reference/getskill.md
  - https://docs.observeinc.com/reference/listalerts.md
  - https://docs.observeinc.com/reference/listapitokens.md
  - https://docs.observeinc.com/reference/listapmenvironments.md
  - https://docs.observeinc.com/reference/listapmservices.md
  - https://docs.observeinc.com/reference/listdashboards.md
  - https://docs.observeinc.com/reference/listdatasetgraph.md
  - https://docs.observeinc.com/reference/listdatasetqueryfilters.md
  - https://docs.observeinc.com/reference/listdatasets-1.md
  - https://docs.observeinc.com/reference/listdatasets.md
  - https://docs.observeinc.com/reference/listdatasettags.md
  - https://docs.observeinc.com/reference/listfilterabledatasets.md
  - https://docs.observeinc.com/reference/listingestfilters.md
  - https://docs.observeinc.com/reference/listingestroutes.md
  - https://docs.observeinc.com/reference/listingesttokens.md
  - https://docs.observeinc.com/reference/listmetrics.md
  - https://docs.observeinc.com/reference/listmonitormuterules.md
  - https://docs.observeinc.com/reference/listmonitormutes.md
  - https://docs.observeinc.com/reference/listmonitors-1.md
  - https://docs.observeinc.com/reference/listserviceaccounts.md
  - https://docs.observeinc.com/reference/listskills.md
  - https://docs.observeinc.com/reference/polldelegatedlogin.md
  - https://docs.observeinc.com/reference/queryreferencetables.md
  - https://docs.observeinc.com/reference/searchdocumentation.md
  - https://docs.observeinc.com/reference/searchobjecttagkeys.md
  - https://docs.observeinc.com/reference/searchobjecttagvalues.md
  - https://docs.observeinc.com/reference/searchtagvalues.md
  - https://docs.observeinc.com/reference/startdelegatedlogin.md
  - https://docs.observeinc.com/reference/updateapitoken.md
  - https://docs.observeinc.com/reference/updatedashboard.md
  - https://docs.observeinc.com/reference/updatedatasetqueryfilter.md
  - https://docs.observeinc.com/reference/updateingestfilter.md
  - https://docs.observeinc.com/reference/updateingestroute.md
  - https://docs.observeinc.com/reference/updateingestroutepriorities.md
  - https://docs.observeinc.com/reference/updateingesttoken.md
  - https://docs.observeinc.com/reference/updatemonitor.md
  - https://docs.observeinc.com/reference/updatemonitormute.md
  - https://docs.observeinc.com/reference/updatereferencetable.md
  - https://docs.observeinc.com/reference/updatereferencetablemetadata.md
  - https://docs.observeinc.com/reference/updateserviceaccount.md
  - https://docs.observeinc.com/reference/updateskill.md
  - https://docs.observeinc.com/reference/validateingestfilterexpression.md
  x-retrieved: '2026-10-13'
  x-source: Assembled verbatim from the OpenAPI 3.1 definitions ReadMe embeds in each of 88 operation pages under https://docs.observeinc.com/reference/ (no single downloadable spec is published); paths and components merged, nothing authored.
  description: 'Operations tagged Dataset Query Filter across 2 of this provider''s published API definitions: observeinc-openapi-assembled.json, observeinc-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{customerid}.observeinc.com
  description: US west server
  variables:
    customerid:
      default: OBSERVE_CUSTOMERID
      description: The customer ID for your instance.
- url: https://{customerid}.{cluster}.observeinc.com
  description: Specific regional cluster (prod)
  variables:
    customerid:
      default: OBSERVE_CUSTOMERID
      description: The customer ID for your instance.
    cluster:
      enum:
      - eu-1
      - ap-1
      default: eu-1
      description: For regional clusters, choose one.
- url: https://{customerid}.{domain}.com
  description: Specific Observe server
  variables:
    customerid:
      default: OBSERVE_CUSTOMERID
      description: The customer ID for your instance.
    domain:
      default: OBSERVE_DOMAIN
      description: The Observe domain for your instance.
security:
- bearerAuth: []
tags:
- name: Dataset Query Filter
  x-displayName: Dataset Query Filter
  description: Manage dataset query filters. Learn more about dataset query filters.
paths:
  /v1/datasets/{datasetId}/query-filters:
    post:
      summary: Create a new dataset query filter
      description: Create a new query filter for a specific dataset
      operationId: CreateDatasetQueryFilter
      tags:
      - Dataset Query Filter
      parameters:
      - $ref: '#/components/parameters/DatasetIdParam'
      - $ref: '#/components/parameters/ExpandParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetQueryFilter-CreateRequest'
      responses:
        '201':
          description: Dataset query filter created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetQueryFilter-Resource'
        '400':
          $ref: '#/components/responses/ErrorResponse-400'
        '401':
          $ref: '#/components/responses/ErrorResponse-401'
        '403':
          $ref: '#/components/responses/ErrorResponse-403'
        '404':
          $ref: '#/components/responses/ErrorResponse-404'
        '429':
          $ref: '#/components/responses/ErrorResponse-429'
        5XX:
          $ref: '#/components/responses/ErrorResponse-5XX'
    get:
      summary: Get a list of dataset query filters
      description: Get a list of all query filters for a specific dataset
      operationId: ListDatasetQueryFilters
      tags:
      - Dataset Query Filter
      parameters:
      - $ref: '#/components/parameters/DatasetIdParam'
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/ExpandParam'
      responses:
        '200':
          description: Dataset query filters retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                - queryFilters
                - meta
                properties:
                  queryFilters:
                    type: array
                    items:
                      $ref: '#/components/schemas/DatasetQueryFilter-Resource'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/ErrorResponse-400'
        '401':
          $ref: '#/components/responses/ErrorResponse-401'
        '403':
          $ref: '#/components/responses/ErrorResponse-403'
        '404':
          $ref: '#/components/responses/ErrorResponse-404'
        '429':
          $ref: '#/components/responses/ErrorResponse-429'
        5XX:
          $ref: '#/components/responses/ErrorResponse-5XX'
    servers:
    - url: https://{customerid}.observeinc.com
      description: US west server
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
    - url: https://{customerid}.{cluster}.observeinc.com
      description: Specific regional cluster (prod)
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
        cluster:
          enum:
          - eu-1
          - ap-1
          default: eu-1
          description: For regional clusters, choose one.
    - url: https://{customerid}.{domain}.com
      description: Specific Observe server
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
        domain:
          default: OBSERVE_DOMAIN
          description: The Observe domain for your instance.
  /v1/datasets/{datasetId}/query-filters/{id}:
    delete:
      summary: Delete a dataset query filter
      description: Delete an existing query filter
      operationId: DeleteDatasetQueryFilter
      tags:
      - Dataset Query Filter
      parameters:
      - $ref: '#/components/parameters/DatasetIdParam'
      - name: id
        in: path
        required: true
        description: The ID of the query filter to delete
        schema:
          type: string
          format: int64
        example: '7890123'
      responses:
        '204':
          description: Dataset query filter deleted successfully
        '400':
          $ref: '#/components/responses/ErrorResponse-400'
        '401':
          $ref: '#/components/responses/ErrorResponse-401'
        '403':
          $ref: '#/components/responses/ErrorResponse-403'
        '404':
          $ref: '#/components/responses/ErrorResponse-404'
        '429':
          $ref: '#/components/responses/ErrorResponse-429'
        5XX:
          $ref: '#/components/responses/ErrorResponse-5XX'
    get:
      summary: Get a dataset query filter by ID
      description: Retrieve a specific query filter by its ID
      operationId: GetDatasetQueryFilterById
      tags:
      - Dataset Query Filter
      parameters:
      - $ref: '#/components/parameters/DatasetIdParam'
      - name: id
        in: path
        required: true
        description: The ID of the query filter to retrieve
        schema:
          type: string
          format: int64
        example: '7890123'
      - $ref: '#/components/parameters/ExpandParam'
      responses:
        '200':
          description: Dataset query filter retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetQueryFilter-Resource'
        '400':
          $ref: '#/components/responses/ErrorResponse-400'
        '401':
          $ref: '#/components/responses/ErrorResponse-401'
        '403':
          $ref: '#/components/responses/ErrorResponse-403'
        '404':
          $ref: '#/components/responses/ErrorResponse-404'
        '429':
          $ref: '#/components/responses/ErrorResponse-429'
        5XX:
          $ref: '#/components/responses/ErrorResponse-5XX'
    patch:
      summary: Update a dataset query filter
      description: Update an existing query filter using JSON Merge Patch semantics
      operationId: UpdateDatasetQueryFilter
      tags:
      - Dataset Query Filter
      parameters:
      - $ref: '#/components/parameters/DatasetIdParam'
      - name: id
        in: path
        required: true
        description: The ID of the query filter to update
        schema:
          type: string
          format: int64
        example: '7890123'
      - $ref: '#/components/parameters/ExpandParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetQueryFilter-UpdateRequest'
      responses:
        '200':
          description: Dataset query filter updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetQueryFilter-Resource'
        '400':
          $ref: '#/components/responses/ErrorResponse-400'
        '401':
          $ref: '#/components/responses/ErrorResponse-401'
        '403':
          $ref: '#/components/responses/ErrorResponse-403'
        '404':
          $ref: '#/components/responses/ErrorResponse-404'
        '429':
          $ref: '#/components/responses/ErrorResponse-429'
        5XX:
          $ref: '#/components/responses/ErrorResponse-5XX'
    servers:
    - url: https://{customerid}.observeinc.com
      description: US west server
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
    - url: https://{customerid}.{cluster}.observeinc.com
      description: Specific regional cluster (prod)
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
        cluster:
          enum:
          - eu-1
          - ap-1
          default: eu-1
          description: For regional clusters, choose one.
    - url: https://{customerid}.{domain}.com
      description: Specific Observe server
      variables:
        customerid:
          default: OBSERVE_CUSTOMERID
          description: The customer ID for your instance.
        domain:
          default: OBSERVE_DOMAIN
          description: The Observe domain for your instance.
components:
  parameters:
    ExpandParam:
      name: expand
      in: query
      description: Whether to expand resources referenced in the response to include additional fields
      schema:
        type: boolean
    OffsetParam:
      name: offset
      in: query
      description: Number of items to skip before starting to collect the result set
      schema:
        type: integer
        format: int64
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return in the response
      schema:
        type: integer
        format: int64
    DatasetIdParam:
      name: datasetId
      in: path
      required: true
      description: The ID of the dataset
      schema:
        type: string
        format: int64
  schemas:
    ObjectId:
      type: string
      format: ObjectId
    Meta:
      description: List Response Metadata
      type: object
      required:
      - totalCount
      properties:
        totalCount:
          description: 'The total number of resources available, independent of pagination.

            The API may return -1 if the total count is unknown or cannot be computed

            in reasonable time.

            '
          type: integer
          format: int64
    DatasetQueryFilter-UpdateRequest:
      title: DatasetQueryFilterUpdateRequest
      type: object
      properties:
        label:
          type: string
          description: Human-readable name for the filter
          minLength: 1
          maxLength: 255
        description:
          type:
          - string
          - 'null'
          description: Long-form description of the filter
        filter:
          type: string
          description: 'Legacy OPAL boolean expression string for the filter predicate (without the leading `filter` verb).


            Deprecated in favor of `pipeline` and may be removed in a future API version. When updating a filter''s semantics, a request may provide either `filter` or `pipeline`, but not both.

            '
          minLength: 1
        pipeline:
          type: string
          description: 'Canonical OPAL pipeline snippet for the filter. May contain only filter verbs (and comments).


            When updating a filter''s semantics, a request may provide either `filter` or `pipeline`, but not both. `pipeline` is preferred, as `filter` may be removed in a future API version.

            '
          minLength: 1
        disabled:
          type: boolean
          description: Whether the filter is disabled by the user
        startTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Activation window start time (inclusive). If omitted, the filter applies from negative infinity (unbounded from the past).
        endTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Activation window end time (exclusive). If omitted, the filter applies to positive infinity (unbounded to the future).
        layout:
          type:
          - string
          - 'null'
          description: UI layout/metadata for the filter builder. This field is used by the Observe UI and should be omitted by other clients.
    User:
      title: User
      type: object
      required:
      - id
      properties:
        id:
          title: User Identifier
          $ref: '#/components/schemas/ObjectId'
        label:
          title: User Label
          type: string
        timezone:
          type: string
        locale:
          type: string
    DatasetQueryFilter-Resource:
      title: DatasetQueryFilter
      type: object
      required:
      - id
      - label
      - filter
      - pipeline
      - disabled
      - createdBy
      - createdAt
      - updatedBy
      - updatedAt
      properties:
        id:
          $ref: '#/components/schemas/ObjectId'
        label:
          type: string
          description: Human-readable name for the filter
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: Long-form description of the filter
        filter:
          type: string
          description: 'Legacy OPAL boolean expression string for the filter predicate (without the leading `filter` verb).


            Deprecated in favor of `pipeline` and may be removed in a future API version. When creating or updating a filter, clients must provide exactly one of `filter` or `pipeline`.

            API responses always include both `filter` and `pipeline`; clients should consume `pipeline`.

            '
          minLength: 1
        pipeline:
          type: string
          description: 'Canonical OPAL pipeline snippet for the filter. May contain only filter verbs (and comments).


            When creating or updating a filter, clients must provide exactly one of `filter` or `pipeline`.

            API responses always include both `filter` and `pipeline`; clients should consume `pipeline`.

            '
          minLength: 1
        disabled:
          type: boolean
          description: Whether the filter is disabled by the user
        errors:
          type: array
          items:
            type: string
          description: List of error messages if the filter has issues (omitted if no errors)
        createdBy:
          $ref: '#/components/schemas/User'
          description: User who created the filter
        createdAt:
          type: string
          format: date-time
          description: When the filter was created
        updatedBy:
          $ref: '#/components/schemas/User'
          description: User who last updated the filter
        updatedAt:
          type: string
          format: date-time
          description: When the filter was last updated
        startTime:
          type: string
          format: date-time
          description: Activation window start time (inclusive). If omitted, the filter applies from negative infinity (unbounded from the past).
        endTime:
          type: string
          format: date-time
          description: Activation window end time (exclusive). If omitted, the filter applies to positive infinity (unbounded to the future).
        layout:
          type: string
          description: UI layout/metadata for the filter builder. This field is used by the Observe UI and should be omitted by other clients.
    ErrorMessage:
      type: object
      properties:
        type:
          type: string
          description: A stable, machine-readable identifier for the kind of error.
        message:
          type: string
          description: Error message
      required:
      - type
      - message
    DatasetQueryFilter-CreateRequest:
      title: DatasetQueryFilterCreateRequest
      type: object
      required:
      - label
      properties:
        label:
          type: string
          description: Human-readable name for the filter
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: Long-form description of the filter
        filter:
          type: string
          description: 'Legacy OPAL boolean expression string for the filter predicate (without the leading `filter` verb).


            Deprecated in favor of `pipeline` and may be removed in a future API version. Exactly one of `filter` or `pipeline` must be provided when creating a filter.

            '
          minLength: 1
        pipeline:
          type: string
          description: 'Canonical OPAL pipeline snippet for the filter. May contain only filter verbs (and comments).


            Exactly one of `filter` or `pipeline` must be provided when creating a filter. `pipeline` is preferred for new integrations, as `filter` may be removed in a future API version.

            '
          minLength: 1
        disabled:
          type: boolean
          description: Whether the filter is disabled by the user
          default: false
        startTime:
          type: string
          format: date-time
          description: Activation window start time (inclusive). If omitted, the filter applies from negative infinity (unbounded from the past).
        endTime:
          type: string
          format: date-time
          description: Activation window end time (exclusive). If omitted, the filter applies to positive infinity (unbounded to the future).
        layout:
          type: string
          description: UI layout/metadata for the filter builder. This field is used by the Observe UI and should be omitted by other clients.
  responses:
    ErrorResponse-404:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-5XX:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-429:
      description: Rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    ErrorResponse-401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: 'Authorization: Bearer <customerid> <apitoken>

        '
x-refined-from:
- observeinc-openapi-assembled.json
- observeinc-openapi.yml