The search query lets you find items, boards, and documents across your entire account in a single API call. This guide walks through common search patterns and shows you how to use filters to get precise results.

🚧
Requests must include the API-Version: 2026-07 header or later. See API versioning for details.

Pre-requisites

API authentication token
Required scopes: boards:read for item and board results, docs:read for document results

Basic search

The simplest search queries all entity types for a keyword. You select which entity types to include via the filters.entities array, and use inline fragments to specify the fields you want for each result type.

query {
  search(
    query: "quarterly report"
    limit: 10
    filters: {
      entities: [
        { items: {} }
        { boards: {} }
        { docs: {} }
      ]
    }
  ) {
    ... on ItemSearchResult {
      id
      entity_type
      score
      data {
        id
        name
        board_name
        url
      }
    }
    ... on BoardSearchResult {
      id
      entity_type
      score
      data {
        id
        name
        url
      }
    }
    ... on DocSearchResult {
      id
      entity_type
      score
      data {
        id
        name
      }
    }
  }
}

👍
Pro tip
The limit applies per entity type. Setting limit: 10 returns up to 10 items, 10 boards, and 10 documents (30 total).

Searching a single entity type

If you only need items, omit boards and docs from the entities array:

query {
  search(
    query: "bug fix"
    limit: 25
    filters: {
      entities: [
        { items: {} }
      ]
    }
  ) {
    ... on ItemSearchResult {
      id
      score
      data {
        id
        name
        board_id
        board_name
        group_name
      }
    }
  }
}

Filtering by workspace or board

Each entity type supports per-entity filters to narrow results to specific workspaces or boards.

Items on specific boards

query {
  search(
    query: "design review"
    limit: 20
    filters: {
      entities: [
        { items: { board_ids: ["1234567890", "9876543210"] } }
      ]
    }
  ) {
    ... on ItemSearchResult {
      id
      data {
        id
        name
        board_name
      }
    }
  }
}

Everything in a workspace

query {
  search(
    query: "roadmap"
    limit: 10
    filters: {
      entities: [
        { items: { workspace_ids: ["12345"] } }
        { boards: { workspace_ids: ["12345"] } }
        { docs: { workspace_ids: ["12345"] } }
      ]
    }
  ) {
    ... on ItemSearchResult {
      id
      entity_type
      data { id name board_name }
    }
    ... on BoardSearchResult {
      id
      entity_type
      data { id name }
    }
    ... on DocSearchResult {
      id
      entity_type
      data { id name }
    }
  }
}

Filtering by date range

Use the date_range filter to narrow results by creation or update timestamps. This filter applies globally across all entity types.

query {
  search(
    query: "sprint planning"
    limit: 10
    filters: {
      date_range: {
        created_after: "2026-01-01T00:00:00Z"
        updated_after: "2026-03-01T00:00:00Z"
      }
      entities: [
        { items: {} }
        { boards: {} }
      ]
    }
  ) {
    ... on ItemSearchResult {
      id
      data {
        id
        name
        created_at
        updated_at
      }
    }
    ... on BoardSearchResult {
      id
      data {
        id
        name
        created_at
        updated_at
      }
    }
  }
}

All four date fields are optional and can be combined:

Field	Description
`created_after`	Only results created after this timestamp
`created_before`	Only results created before this timestamp
`updated_after`	Only results updated after this timestamp
`updated_before`	Only results updated before this timestamp

Accessing item column values

Item results include pre-indexed column values, so you can inspect column data without making a separate query:

query {
  search(
    query: "critical"
    limit: 5
    filters: {
      entities: [
        { items: { board_ids: ["1234567890"] } }
      ]
    }
  ) {
    ... on ItemSearchResult {
      id
      data {
        name
        board_name
        column_values {
          id
          col_type
          col_title
          value
        }
      }
    }
  }
}

Each column value includes its col_type and col_title, making it straightforward to identify and process values programmatically.

Using `live_data` for real-time fields

Each result type has a live_data field that resolves to the full entity from the core API (Item, Board, or Document). Use this when you need fields that aren't available in the indexed data, such as nested relationships:

query {
  search(
    query: "onboarding"
    limit: 5
    filters: {
      entities: [
        { items: {} }
      ]
    }
  ) {
    ... on ItemSearchResult {
      id
      data {
        name
        board_name
      }
      live_data {
        id
        name
        state
        column_values {
          id
          text
        }
      }
    }
  }
}

📘
NOTE
The data field returns pre-indexed data — fast but potentially stale. The live_data field fetches the latest data from the core API, which adds latency but ensures freshness. Use data when speed matters and live_data when you need real-time accuracy.

JavaScript SDK example

import { ApiClient } from "@mondaydotcomorg/api";

const client = new ApiClient({ token: "YOUR_API_TOKEN" });

const query = `query {
  search(
    query: "Q1 planning"
    limit: 10
    filters: {
      entities: [
        { items: { workspace_ids: ["12345"] } }
        { boards: {} }
      ]
    }
  ) {
    ... on ItemSearchResult {
      id
      entity_type
      score
      data { id name board_name }
    }
    ... on BoardSearchResult {
      id
      entity_type
      score
      data { id name }
    }
  }
}`;

const response = await client.request(query);
console.log(response);

Limits and best practices

Constraint	Value
Maximum `limit` value	`100` per entity type
Pagination	Not supported — all results returned up to `limit`

Best practices:

Request only the entity types you need. Omitting entity types from the filters.entities array avoids unnecessary processing.
Use per-entity filters (board_ids, workspace_ids) to narrow the result set and improve relevance.
Prefer data over live_data for read-heavy use cases where milliseconds of staleness are acceptable.
Use date_range filters to scope results to a relevant time window, especially in accounts with large amounts of data.
Use specific search terms. More specific queries return more relevant results.

Pre-requisites

Basic search

Pro tip

Searching a single entity type

Filtering by workspace or board

Items on specific boards

Everything in a workspace

Filtering by date range

Accessing item column values

Using live_data for real-time fields

NOTE

JavaScript SDK example

Limits and best practices

Using `live_data` for real-time fields