---
title: "Search teams"
method: POST
path: "/teams/search"
tags: ["teams"]
---

# Search teams

`POST /teams/search`

## Purpose
Performs a filtered search over teams using a POST request.
Use this endpoint for batch lookups by IDs, names, or handles when query string filters are insufficient.

## Request Format

Uses structured `filter` and `search` objects.

## Key Features
- `filter.id`: Filter by team UUIDs (OR logic, max 100)
- `filter.fields.name`: Filter by team name, case-insensitive (single string or array, OR logic)
- `filter.fields.handle`: Filter by team handle, case-insensitive (single string or array, OR logic)
- `search.query`: Full-text search on team name and handle (case-insensitive partial match)
- Returns the same response format as `GET /v2/teams`

## Filter Logic
- Multiple values within a single filter use **OR** logic (e.g., `filter.fields.name: ["A", "B"]` returns teams named A or B)
- Different filter types and search use **AND** logic (e.g., `filter` AND `search` = intersection)
- Empty request returns all teams (same as `GET /v2/teams`)

## Important Notes
- Each filter array accepts at most 100 items; exceeding this returns a 400 error
- Pagination uses cursor-based navigation via `pageCursor` query parameter

## Query parameters

- `pageCursor` string

## Request body

- TeamSearchRequest — Request body for searching teams with filters.
  - `data` TeamSearchData — Search data with structured filter and search objects.
    - `filter` TeamSearchFilter — Structured filters for team search. Different filter groups use AND logic. All filters are optional.
      - `id` union — Filter by team UUIDs (OR logic).
        - string, uuid — A universally unique identifier (UUID).
        - UUID[]
      - `fields` TeamSearchFilterFields — Field-level filters. Multiple values within a field use OR logic. String matching is case-insensitive.
        - `name` union — Filter by team name. Single string or array (OR logic), case-insensitive.
          - string
          - string[]
        - `handle` union — Filter by team handle. Single string or array (OR logic), case-insensitive.
          - string
          - string[]
    - `search` TeamSearchSearch — Full-text search options. Combined with filters using AND logic.
      - `query` string — Full-text search query. Performs case-insensitive partial match on team name and handle.

## Response `200`

A paginated list of teams

- object
  - `data` Team[]
    - `id` string, uuid, required — Unique identifier of the team
    - `type` 'team', required — Resource type identifier
    - `links` TeamLinks, required — Links for navigating team resources.
      - `self` string, uri, required — URL of the team resource.
      - `members` string, uri, required — URL of the paginated team members sub-resource.
      - `html` string, uri, required — URL of the team page in the Productboard UI.
    - `fields` TeamFields, required — Fields of a team resource.
      - `name` string, required — The name of the team.
      - `handle` string, required — Unique handle for @mentions. Lowercase alphanumeric only.
      - `description` string — Optional description of the team.
      - `avatarUrl` string, uri, nullable — URL of the team's avatar image. Read-only. Returns `null` if no avatar is set.
    - `createdAt` string, date-time, required — ISO 8601 timestamp when the team was created
    - `updatedAt` string, date-time, required — ISO 8601 timestamp when the team was last updated
  - `links` ListLinks
    - `next` string, nullable, required

## Other responses

- `400` — Bad Request - Invalid input format or malformed request
- `401` — Unauthorized - Missing or invalid authentication credentials
- `403` — Forbidden - Insufficient permissions
- `408` — Request Timeout - The server did not receive a complete request within the allowed time
- `422` — Unprocessable Entity - Validation failed (e.g., missing required fields, unknown fields)
- `429` — Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time
- `500` — Internal Server Error - An unexpected error occurred on the server, please retry or contact support

---

[API](https://skmtc.dev/productboard/apis/notes.md) · [All operations](https://skmtc.dev/productboard/apis/notes/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/productboard/notes/revisions/b4004749b60f/schema)