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

# Query Tasks

> Retrieve a list of tasks matching a dynamic filter.



## OpenAPI

````yaml POST /api/tasks/query
openapi: 3.0.1
info:
  title: EZYiD API
  version: '1.0'
servers:
  - url: https://api-external.ezyid.io
security: []
tags:
  - name: EZYiD.External.API
paths:
  /api/tasks/query:
    post:
      tags:
        - EZYiD.External.API
      summary: List tasks matching a dynamic filter
      description: >-
        Returns one row per scheduled task occurrence. The time range shorthand
        applies to `dueDate`. Status and priority accept either their numeric
        code or their label.
      operationId: EZYiDExternalAPITasksQueryTasks
      parameters:
        - name: apiKey
          in: query
          required: true
          schema:
            type: string
      requestBody:
        description: >-
          Every part is optional. An empty object returns the first page of the
          subscriber's tasks.
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatasetQueryRequest'
            example:
              filters:
                clauses:
                  - fieldId: taskStatus
                    operator: notIn
                    value:
                      - Completed
                  - fieldId: isOverdue
                    operator: eq
                    value: true
                  - fieldId: priority
                    operator: eq
                    value: High
              sort:
                - fieldId: dueDate
                  direction: asc
              fields:
                - id
                - title
                - taskStatus
                - priority
                - dueDate
                - siteName
                - assigneeCount
              rows: 50
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetQueryResponse'
        '400':
          description: >-
            The API key is missing, or the filter, sort or paging window was
            rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetQueryError'
        '401':
          description: The API key is revoked or expired.
        '404':
          description: The API key does not exist.
components:
  schemas:
    DatasetQueryRequest:
      type: object
      description: >-
        Which rows to match, how to sort them, which fields to return and which
        page to read.
      properties:
        filters:
          $ref: '#/components/schemas/DatasetFilterGroup'
        timeRange:
          $ref: '#/components/schemas/DatasetTimeRange'
        sort:
          type: array
          description: >-
            At most two rules. The dataset's unique key always breaks ties, so
            paging is stable.
          items:
            $ref: '#/components/schemas/DatasetSortSpec'
          nullable: true
        fields:
          type: array
          description: Field ids to return. Omit for every field in the dataset's catalog.
          items:
            type: string
          nullable: true
        start:
          type: integer
          format: int32
          description: Rows to skip. Defaults to 0.
          default: 0
        rows:
          type: integer
          format: int32
          description: Page size, between 1 and 1000. Defaults to 100.
          default: 100
          nullable: true
    DatasetQueryResponse:
      type: object
      properties:
        count:
          type: integer
          format: int32
          description: Total rows matching the filter, not the number returned.
        start:
          type: integer
          format: int32
        rows:
          type: integer
          format: int32
          description: Page size the query ran with.
        items:
          type: array
          description: >-
            One object per row, keyed by field id, holding only the requested
            fields. A field with no value is null.
          items:
            type: object
            additionalProperties: true
    DatasetQueryError:
      type: object
      properties:
        error:
          type: string
          description: >-
            What was wrong with the request, naming the field or operator at
            fault.
    DatasetFilterGroup:
      type: object
      description: >-
        A set of clauses and nested groups joined by one operator. Groups may
        nest two levels deep and carry at most 20 clauses in total.
      properties:
        logic:
          type: string
          description: How this group's clauses and sub-groups are joined.
          enum:
            - and
            - or
          default: and
          nullable: true
        clauses:
          type: array
          items:
            $ref: '#/components/schemas/DatasetFilterClause'
          nullable: true
        groups:
          type: array
          items:
            $ref: '#/components/schemas/DatasetFilterGroup'
          nullable: true
    DatasetTimeRange:
      type: object
      description: >-
        Shorthand window over the dataset's defaultDateFieldId. Supply either a
        preset or both from and to, never both. Windows are half-open in UTC:
        from is included, to is not.
      properties:
        preset:
          type: string
          enum:
            - today
            - last7Days
            - last30Days
            - last90Days
            - last12Months
            - thisMonth
            - thisQuarter
            - thisYear
          nullable: true
        from:
          type: string
          format: date-time
          nullable: true
        to:
          type: string
          format: date-time
          nullable: true
    DatasetSortSpec:
      type: object
      properties:
        fieldId:
          type: string
        direction:
          type: string
          enum:
            - asc
            - desc
          default: asc
          nullable: true
    DatasetFilterClause:
      type: object
      description: >-
        One condition on one field. The operator must be listed for that field
        in the dataset's catalog.
      properties:
        fieldId:
          type: string
          description: Field id from the dataset's catalog.
        operator:
          type: string
          enum:
            - eq
            - neq
            - gt
            - gte
            - lt
            - lte
            - between
            - contains
            - startsWith
            - in
            - notIn
            - isEmpty
            - isNotEmpty
        value:
          description: >-
            A scalar for most operators, an array for in and notIn, and omitted
            for isEmpty and isNotEmpty. Dates are strings, for example
            "2026-01-31".
        endValue:
          description: Upper bound, required by between and ignored otherwise.

````