---
title: "Search Lists"
method: POST
path: "/crm/lists/2026-09/search"
tags: ["Search"]
---

# Search Lists

`POST /crm/lists/2026-09/search`

## Request

- Base URL: `https://api.hubapi.com`
- URL: `https://api.hubapi.com/crm/lists/2026-09/search`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://app.hubspot.com/oauth/authorize`
    - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.segments.read`
  - OAuth 2
    - Authorization code: `https://app.hubspot.com/oauth/authorize`
    - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.lists.read`

Search for lists within your HubSpot account using various criteria. This endpoint allows you to filter and retrieve lists based on specific search parameters, making it easier to manage and organize your lists effectively.

## Request body

- ListSearchRequest
  - `additionalProperties` string[], required: An array of strings representing additional properties to include in the search.
  - `count` integer: An integer specifying the number of results to return.
  - `listIds` string[], required: An array of strings specifying the IDs of the lists to search.
  - `objectTypeId` string: A string representing the object type ID to filter the lists.
  - `offset` integer, required: An integer used for pagination, indicating the starting point for the search results.
  - `processingTypes` string[], required: An array of strings indicating the types of processing to apply to the search results.
  - `query` string: A string representing the search query to filter the lists.
  - `sort` string: A string specifying the sorting criteria for the search results.

## Response `200`

successful operation

- ListSearchResponse
  - `hasMore` boolean, required: A boolean indicating whether there are more results available beyond the current page.
  - `lists` PublicObjectListSearchResult[], required: An array of objects representing the lists found in the search, each conforming to the PublicObjectListSearchResult schema.
    - `additionalProperties` object, required: An object containing additional properties of the list, with each property represented as a string.
    - `createdAt` string, date-time: The date and time when the list was created, in ISO 8601 format.
    - `createdById` string: The unique identifier of the user who created the list, represented as a string.
    - `deletedAt` string, date-time: The date and time when the list was deleted, in ISO 8601 format.
    - `filtersUpdatedAt` string, date-time: The date and time when the list's filters were last updated, in ISO 8601 format.
    - `listId` string, required: The unique identifier for the list, represented as a string.
    - `listVersion` integer, required: An integer indicating the version of the list.
    - `name` string, required: The name of the list, represented as a string.
    - `objectTypeId` string, required: The unique identifier for the type of object associated with the list, represented as a string.
    - `processingStatus` string, required: A string representing the current processing status of the list.
    - `processingType` string, required: A string indicating the type of processing applied to the list.
    - `updatedAt` string, date-time: The date and time when the list was last updated, in ISO 8601 format.
    - `updatedById` string: The unique identifier of the user who last updated the list, represented as a string.
  - `offset` integer, required: An integer indicating the position in the list of results where the current page starts.
  - `total` integer, required: An integer indicating the total number of lists found by the search.

## Other responses

- `default`: An error occurred.

## Changes

- **2026-10-10** (2026-09) `e1dd745172d1`: 2 info
  - the security scope `crm.segments.read` was added to the endpoint's security scheme `oauth2`
  - the security scope `crm.lists.read` was removed from the endpoint's security scheme `oauth2`
- **2026-09-07** (2026-09) `6d0e6dc36ca0`: 2 info
  - the security scope `crm.segments.read` was added to the endpoint's security scheme `oauth2`
  - the security scope `crm.lists.read` was removed from the endpoint's security scheme `oauth2`

[Operation history](https://skmtc.dev/hubspot/apis/crm-lists/changes/crm/lists/2026-09/search/post.md)

---

[API](https://skmtc.dev/hubspot/apis/crm-lists.md) - [All operations](https://skmtc.dev/hubspot/apis/crm-lists/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/crm-lists/revisions/e1dd745172d1?raw)