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

# Search Cases

> Search cases in a queue with rich filters (multi-status, date ranges, label-based filters, and field-value filters over a typed queue's json_data). Use this when the simple query-string filters on GET /v2/queues/:queue_id/cases aren't enough. Each json_data entry is {path, operator, value} where path is a declared scalar in JSONPath dotted form ($.invoice.amount); entries are ANDed, so two comparisons on one path express a range. A path the queue's Case schema does not declare is rejected rather than ignored, as is a value that does not match the field's declared type. The contains operator is case-sensitive (unlike the free-text search parameter). Set count_only=true to skip Case row selection, enrichment, and transformation. The normal response shape is returned with cases: [] and the matching total.



## OpenAPI

````yaml https://api.duvo.ai/v2/documentation/mintlify.json post /v2/queues/{queue_id}/cases/search
openapi: 3.0.3
info:
  title: Duvo Public API
  description: >-
    Public API for programmatic access to Duvo. Authenticate with API keys
    created in the Duvo dashboard.


    ## Rate limits


    Requests are counted per API key. Every response advertises the quota with
    the IETF RateLimit fields, so a client can self-throttle without waiting for
    a rejection:


    - `RateLimit-Policy: "default";q=<quota>;w=<window seconds>` — the policy in
    force: `q` requests per `w` seconds.

    - `RateLimit: "default";r=<remaining>;t=<seconds>` — the live state: `r`
    requests left, quota resetting in `t` seconds.

    - Read the quota from the headers rather than hard-coding it; it differs per
    environment.

    - The same numbers are also sent as `ratelimit-limit`, `ratelimit-remaining`
    and `ratelimit-reset`.


    Once the quota is exhausted the API answers `429 Too Many Requests` with
    `Retry-After` set to the seconds to wait; honor it instead of retrying
    immediately.
  version: 1.0.0
servers:
  - url: https://api.duvo.ai
    description: Production server
security: []
tags:
  - name: Runs
    description: Start, monitor, and manage agent runs (Runs in the Duvo UI)
  - name: Sandboxes
    description: Create sandboxes and upload files for agent runs
  - name: Queues
    description: Manage queues and their agent bindings
  - name: Cases
    description: Create, list, and manage cases and their labels within queues
  - name: Case Approvals
    description: Submit decisions on pending case approval requests issued by an agent run
  - name: Case Attachments
    description: Upload, list, download, and remove the files attached to a case
  - name: Automations
    description: >-
      List and manage automations — the workspace container that groups the
      agents and queues making up one end-to-end process
  - name: Agents
    description: Create and manage agents for automation workloads
  - name: Revisions
    description: Create and manage agent revisions — the underlying Setup for an Agent
  - name: Agent Folders
    description: Organize agents into folders
  - name: Agent Memory
    description: Read an agent's memory files (the Memory feature in the Duvo UI)
  - name: Suggestions
    description: >-
      List, apply, and dismiss an Agent's improvement suggestions (the
      suggestions inbox in the Duvo UI)
  - name: Notifications
    description: >-
      List, read, dismiss, and clear the authenticated user's team notifications
      (the Notification Center in the Duvo UI)
  - name: Schedules
    description: List schedules configured for an agent
  - name: Duvo Pulse
    description: >-
      Create, list, iterate on, and delete Duvo Pulse dashboards — live,
      agent-generated visualizations of your Duvo data
  - name: Case Triggers
    description: >-
      Configure case triggers that automatically dispatch agent runs (Runs in
      the Duvo UI) for cases added to a queue
  - name: Triggers
    description: >-
      Configure event triggers that start a Run automatically when an external
      event fires (e.g. an email arrives, a Linear issue is created, or a file
      changes in Google Drive)
  - name: Skills
    description: Manage team and system skills (reusable knowledge packs).
  - name: Files
    description: Manage team files.
  - name: Plugins
    description: Discover plugins that can be referenced from a revision.
  - name: Organizations
    description: Inspect organizations you belong to and the teams within them
  - name: Team
    description: Inspect the team and members associated with the API key
  - name: Invites
    description: >-
      Invite people to a team — one at a time or in bulk, scoped to a Clarity
      process or the whole team — and manage the team's shareable invite link
  - name: Integrations
    description: Browse the team's catalog of available integration types
  - name: Connections
    description: Manage your connected integrations
  - name: Credentials
    description: >-
      Manage logins (domain + username + password + TOTP) used by agents to sign
      in to websites and desktop applications, and attach them to assignment
      revisions
  - name: Secrets
    description: >-
      Manage env-var secrets injected into runs, and attach them to assignment
      revisions. Only metadata is exposed; values are never returned
  - name: Revision Integrations
    description: >-
      Attach integrations to assignment revisions, pin specific connections, and
      link queues
  - name: ClarityV2
    description: >-
      Manage Clarity v2 process snapshots, automation proposals, and the
      extra-capture-request follow-up loop
paths:
  /v2/queues/{queue_id}/cases/search:
    post:
      tags:
        - Cases
      summary: Search Cases
      description: >-
        Search cases in a queue with rich filters (multi-status, date ranges,
        label-based filters, and field-value filters over a typed queue's
        json_data). Use this when the simple query-string filters on GET
        /v2/queues/:queue_id/cases aren't enough. Each json_data entry is {path,
        operator, value} where path is a declared scalar in JSONPath dotted form
        ($.invoice.amount); entries are ANDed, so two comparisons on one path
        express a range. A path the queue's Case schema does not declare is
        rejected rather than ignored, as is a value that does not match the
        field's declared type. The contains operator is case-sensitive (unlike
        the free-text search parameter). Set count_only=true to skip Case row
        selection, enrichment, and transformation. The normal response shape is
        returned with cases: [] and the matching total.
      operationId: searchCases
      parameters:
        - schema:
            type: string
            format: uuid
          in: path
          name: queue_id
          required: true
          description: The queue's unique identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  default: {}
                  type: object
                  properties:
                    status:
                      type: array
                      items:
                        type: string
                        enum:
                          - all
                          - pending
                          - processing
                          - needs_input
                          - postponed
                          - needs_review
                          - resolved
                          - canceled
                          - claimed
                          - completed
                          - failed
                    issue_severity:
                      type: array
                      items:
                        type: string
                        enum:
                          - critical
                          - medium
                    failure_source:
                      description: >-
                        Keep only failed Cases, by who failed them: `system`
                        when Duvo could not finish the Case, `manual` when a
                        person marked it failed.
                      type: array
                      items:
                        type: string
                        enum:
                          - system
                          - manual
                    awaiting_my_approval:
                      type: boolean
                    priority:
                      type: array
                      items:
                        type: string
                        enum:
                          - none
                          - medium
                          - high
                    created_at_from:
                      type: string
                    created_at_to:
                      type: string
                    updated_at_from:
                      type: string
                    updated_at_to:
                      type: string
                    completed_at_from:
                      description: >-
                        Keep Cases that reached an outcome at or after this time
                        (inclusive). An ISO timestamp or a lookback such as `7d`
                        or `12h`.
                      type: string
                    completed_at_to:
                      description: >-
                        Keep Cases that reached an outcome before this time
                        (exclusive). An ISO timestamp or a lookback such as `7d`
                        or `12h`.
                      type: string
                    labels:
                      type: object
                      additionalProperties:
                        type: array
                        items:
                          type: string
                    json_data:
                      maxItems: 12
                      type: array
                      items:
                        type: object
                        properties:
                          path:
                            type: string
                            pattern: ^\$(\.[A-Za-z_][A-Za-z0-9_]{0,63})+$
                          operator:
                            type: string
                            enum:
                              - equals
                              - notEquals
                              - in
                              - notIn
                              - gt
                              - gte
                              - lt
                              - lte
                              - contains
                              - isSet
                              - isNotSet
                          value:
                            anyOf:
                              - anyOf:
                                  - type: string
                                  - type: number
                                  - type: boolean
                              - minItems: 1
                                maxItems: 100
                                type: array
                                items:
                                  anyOf:
                                    - type: string
                                    - type: number
                                    - type: boolean
                        required:
                          - path
                          - operator
                        additionalProperties: false
                limit:
                  default: 25
                  type: integer
                  minimum: 1
                  maximum: 100
                offset:
                  default: 0
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                sort_by:
                  default: created_at
                  type: string
                  enum:
                    - created_at
                    - updated_at
                    - postponed_to
                sort_order:
                  default: desc
                  type: string
                  enum:
                    - asc
                    - desc
                search:
                  type: string
                count_only:
                  description: >-
                    Skip Case row selection, enrichment, and transformation. The
                    normal response shape contains an empty cases array and the
                    matching total.
                  type: boolean
                include_blockers:
                  description: >-
                    Also return `blocker` on each case: for a case waiting to
                    start, why the dispatcher cannot start it now, or null when
                    nothing blocks it. Off by default, because it adds database
                    reads; when off, `blocker` is left out.
                  type: boolean
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  cases:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        queue_id:
                          type: string
                          format: uuid
                        title:
                          type: string
                        data:
                          type: string
                        json_data:
                          nullable: true
                          type: object
                          additionalProperties: {}
                        json_schema_id:
                          nullable: true
                          type: string
                          format: uuid
                        status:
                          type: string
                          enum:
                            - pending
                            - completed
                            - failed
                        priority:
                          type: string
                          enum:
                            - none
                            - medium
                            - high
                        display_status:
                          type: string
                          enum:
                            - pending
                            - in_progress
                            - needs_input
                            - postponed
                            - evaluating
                            - success
                            - issues
                            - completed
                            - failed
                            - canceled
                        outcome_source:
                          nullable: true
                          type: string
                          enum:
                            - system
                            - eval
                            - manual
                        outcome_severity:
                          nullable: true
                          type: string
                          enum:
                            - critical
                            - medium
                            - low
                        claimed_at:
                          type: string
                          nullable: true
                        claimed_by_run_id:
                          type: string
                          nullable: true
                        completed_at:
                          type: string
                          nullable: true
                        postponed_to:
                          type: string
                          nullable: true
                        created_at:
                          type: string
                        updated_at:
                          type: string
                        created_by_user_id:
                          nullable: true
                          type: string
                          format: uuid
                        created_by_user_name:
                          type: string
                          nullable: true
                        created_by_user_email:
                          type: string
                          nullable: true
                        agent_run_status:
                          type: string
                          nullable: true
                        agent_run_user_id:
                          nullable: true
                          type: string
                          format: uuid
                        pending_human_request_id:
                          nullable: true
                          type: string
                          format: uuid
                        pending_human_request_type:
                          description: >-
                            Type of the pending human request: 'approval' for a
                            decision, 'question' for an answer, 'credentials'
                            for a login, or 'input' on a module's sample cases.
                            Null when nothing is waiting.
                          nullable: true
                          type: string
                        pending_approval_batch_id:
                          nullable: true
                          type: string
                          format: uuid
                        pending_approval_assignee_user_ids:
                          type: array
                          items:
                            type: string
                            format: uuid
                        approval_approved_count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        approval_rejected_count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        eval_summary:
                          nullable: true
                          type: object
                          properties:
                            evaluationId:
                              type: string
                              format: uuid
                            passed:
                              type: number
                            total:
                              type: number
                            final_comment:
                              type: string
                            status:
                              type: string
                              enum:
                                - ready
                                - unavailable
                                - in_progress
                            severityCounts:
                              type: object
                              properties:
                                critical:
                                  type: integer
                                  minimum: 0
                                  maximum: 9007199254740991
                                medium:
                                  type: integer
                                  minimum: 0
                                  maximum: 9007199254740991
                                low:
                                  type: integer
                                  minimum: 0
                                  maximum: 9007199254740991
                              required:
                                - critical
                                - medium
                                - low
                              additionalProperties: false
                          required:
                            - passed
                            - total
                            - status
                          additionalProperties: false
                        search_match_data_snippet:
                          type: object
                          properties:
                            before:
                              type: string
                            match:
                              type: string
                            after:
                              type: string
                          required:
                            - before
                            - match
                            - after
                          additionalProperties: false
                        labels:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                              key:
                                type: string
                              value:
                                type: string
                                minLength: 1
                              color_hue:
                                type: integer
                                minimum: 0
                                maximum: 360
                            required:
                              - id
                              - key
                              - value
                              - color_hue
                            additionalProperties: false
                        source_automation_revision_id:
                          description: >-
                            The automation revision that produced the case. It
                            never changes. Null when no Run created the case
                            (added through the API or an import, or created
                            before automation revisions), and on a team without
                            automation revisions.
                          nullable: true
                          type: string
                          format: uuid
                        automation_revision_id:
                          description: >-
                            The automation revision that handles the case. It is
                            set when a Run creates the case, set again to the
                            revision that runs the case when a Run claims it,
                            and otherwise changes only when an activation moves
                            waiting cases. For a case that no Run created, null
                            until a Run claims it or an activation moves it.
                            Null on a team without automation revisions.
                          nullable: true
                          type: string
                          format: uuid
                        automation_revision:
                          description: >-
                            The handling revision, resolved. Null when the case
                            has no handling revision.
                          nullable: true
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: The handling revision's ID.
                            status:
                              type: string
                              enum:
                                - draft
                                - live
                                - historic
                              description: >-
                                The revision's lifecycle status. A discarded
                                draft, or a revision that no longer exists,
                                reads as `draft`.
                            revision_number:
                              nullable: true
                              description: >-
                                The revision's number. Null for a draft, which
                                is numbered only when it is activated.
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            name:
                              nullable: true
                              description: The revision's name, if it has one.
                              type: string
                            is_live:
                              type: boolean
                              description: >-
                                Whether this is the automation's live revision
                                right now.
                            hold_reason:
                              description: >-
                                Why the waiting case is held, or null when it is
                                not. A case pinned to an older revision, or to
                                one of another automation, waits rather than
                                running on the live revision when that revision
                                cannot run it. Running it on the live revision,
                                failing it, or fixing the cause releases it.
                              nullable: true
                              type: string
                              enum:
                                - queue_left_automation
                                - queue_not_in_revision
                                - queue_unrouted
                                - agent_deleted
                                - agent_moved
                                - agent_not_bound
                                - build_deleted
                                - route_switched_off
                                - draft_discarded
                          required:
                            - id
                            - status
                            - revision_number
                            - name
                            - is_live
                          additionalProperties: false
                        blocker:
                          description: >-
                            Why the waiting case cannot start right now, when
                            its Queue's setup_status does not already say so.
                            Null when the case is not waiting or nothing blocks
                            it. Present only when the read set include_blockers
                            and the feature is enabled for the team.
                          nullable: true
                          type: object
                          properties:
                            reason:
                              type: string
                              description: >-
                                `connection_missing` or `connection_broken` when
                                a Connection the case's Agent needs cannot be
                                used for the person the case runs as;
                                `pinned_draft` when the case is pinned to a
                                draft that cannot run it;
                                `assigned_agent_not_ready` when the Agent the
                                case is assigned to has no Build to run.
                              x-extensible-enum:
                                - connection_missing
                                - connection_broken
                                - pinned_draft
                                - assigned_agent_not_ready
                            agent:
                              nullable: true
                              description: >-
                                The Agent the case would run on. Null when a
                                draft routes the case to no Agent.
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  description: The Agent's ID.
                                name:
                                  type: string
                                  description: The Agent's current name.
                              required:
                                - id
                                - name
                              additionalProperties: false
                            connections:
                              type: array
                              items:
                                type: object
                                properties:
                                  integration_type:
                                    type: string
                                    description: >-
                                      The Connection's catalog integration type,
                                      e.g. "gmail".
                                  custom_integration_id:
                                    nullable: true
                                    description: >-
                                      The custom Connection's ID, or null for a
                                      catalog Connection.
                                    type: string
                                    format: uuid
                                  name:
                                    type: string
                                    description: The Connection's name.
                                  personal:
                                    type: boolean
                                    description: >-
                                      True when the account is the runner's own
                                      personal account, which only that person
                                      can reconnect. False for a shared account,
                                      or when no account is set up.
                                required:
                                  - integration_type
                                  - custom_integration_id
                                  - name
                                  - personal
                                additionalProperties: false
                              description: >-
                                The Connections a `connection_missing` or
                                `connection_broken` reason names. Empty for
                                every other reason.
                            runner:
                              nullable: true
                              description: >-
                                The person whose Connections the case's run
                                uses. Null when the reason does not depend on
                                Connections.
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                  description: The person's user ID.
                                name:
                                  type: string
                                  description: The person's name.
                              required:
                                - id
                                - name
                              additionalProperties: false
                          required:
                            - reason
                            - agent
                            - connections
                            - runner
                          additionalProperties: false
                      required:
                        - id
                        - queue_id
                        - title
                        - data
                        - status
                        - priority
                        - display_status
                        - claimed_at
                        - claimed_by_run_id
                        - completed_at
                        - postponed_to
                        - created_at
                        - updated_at
                        - created_by_user_id
                        - created_by_user_name
                        - created_by_user_email
                        - agent_run_status
                        - agent_run_user_id
                        - pending_human_request_id
                        - pending_approval_batch_id
                        - pending_approval_assignee_user_ids
                        - approval_approved_count
                        - approval_rejected_count
                        - labels
                      additionalProperties: false
                  total:
                    type: number
                  limit:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  offset:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                required:
                  - cases
                  - total
                  - limit
                  - offset
                additionalProperties: false
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  code:
                    type: string
                  answer_persisted:
                    type: boolean
                  validationErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                      required:
                        - field
                        - message
                      additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  code:
                    type: string
                  answer_persisted:
                    type: boolean
                  validationErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                      required:
                        - field
                        - message
                      additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  code:
                    type: string
                  answer_persisted:
                    type: boolean
                  validationErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                      required:
                        - field
                        - message
                      additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  code:
                    type: string
                  answer_persisted:
                    type: boolean
                  validationErrors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                      required:
                        - field
                        - message
                      additionalProperties: false
                required:
                  - error
                additionalProperties: false
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your API key from the Duvo dashboard.

````

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