> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Search lists > Search and filter saved lists with pagination and sorting. **Filters**: `keywords` (name search), `list_type`, `is_archived`, `owner_ids`, `is_public`. **Sorting**: `name`, `created_at`, `updated_at`, `item_count`. Returns list metadata with item counts, owners, and creator info. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/lists/search openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/lists/search: post: tags: - Lists summary: Search lists description: >- Search and filter saved lists with pagination and sorting. **Filters**: `keywords` (name search), `list_type`, `is_archived`, `owner_ids`, `is_public`. **Sorting**: `name`, `created_at`, `updated_at`, `item_count`. Returns list metadata with item counts, owners, and creator info. operationId: searchLists requestBody: content: application/json: schema: $ref: '#/components/schemas/ListsSearchBody' responses: '200': description: Successful search response content: application/json: schema: $ref: '#/components/schemas/ListsSearchResponse' example: success: true data: - id: aaa11111-bbbb-cccc-dddd-eeeeeeee1111 name: Engineering Candidates Q2 list_type: persons is_public: true is_archived: false linked_job_id: fff66666-0000-1111-2222-333333336666 linked_person_id: null linked_organization_company_id: null item_count: 42 created_by: id: bbb22222-cccc-dddd-eeee-ffffffff2222 first_name: Jane last_name: Smith owners: - id: bbb22222-cccc-dddd-eeee-ffffffff2222 first_name: Jane last_name: Smith created_at: '2024-01-15T10:00:00Z' updated_at: '2024-05-20T14:30:00Z' meta: total: 100 offset: 0 limit: 20 '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: ListsSearchBody: type: object properties: offset: type: integer minimum: 0 default: 0 description: Records to skip for pagination. Defaults to 0. limit: type: integer minimum: 1 maximum: 100 default: 100 description: Max records to return (1–100). Defaults to 100. sort_by: type: string enum: - name - created_at - updated_at - item_count default: created_at description: >- Column to sort by. Accepted values: name, created_at, updated_at, item_count. Defaults to created_at. sort_order: type: string enum: - asc - desc default: desc description: Sort direction. Defaults to desc (newest first). keywords: type: string description: >- Search keyword to filter lists by name. Case-insensitive partial match. list_type: type: string enum: - persons - companies description: >- Filter by list type: "persons" or "companies". Omit to return all types. is_archived: type: boolean default: false description: >- When true, return archived lists only. When false (default), return non-archived lists. owner_ids: type: array items: type: string format: uuid description: Filter to lists owned by these team member UUIDs. is_public: type: boolean description: Filter by public/private visibility. Omit to return both. ListsSearchResponse: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/List' meta: type: object properties: total: type: number description: Total matching records across all pages. offset: type: number description: Current pagination offset. limit: type: number description: Page size used for this request. required: - total - offset - limit required: - success - data - meta List: type: object properties: id: type: string format: uuid description: Unique list UUID. name: type: string description: List name. list_type: type: string enum: - persons - companies description: 'Type of entities in this list: "persons" or "companies".' is_public: type: boolean description: Whether the list is visible to all team members. is_archived: type: boolean description: Whether the list has been archived. linked_job_id: type: - string - 'null' format: uuid description: Job UUID this list is linked to, if any. linked_person_id: type: - string - 'null' format: uuid description: Person UUID this list is linked to, if any. linked_organization_company_id: type: - string - 'null' format: uuid description: Company UUID this list is linked to, if any. item_count: type: number description: Number of non-deleted items in the list. created_by: type: - object - 'null' properties: id: type: string format: uuid description: Team member UUID. first_name: type: - string - 'null' description: Creator first name. last_name: type: - string - 'null' description: Creator last name. required: - id - first_name - last_name description: Team member who created the list. owners: type: array items: type: object properties: id: type: string format: uuid description: Team member UUID. Matches IDs from GET /v1/team-members. first_name: type: - string - 'null' description: Team member first name. last_name: type: - string - 'null' description: Team member last name. required: - id - first_name - last_name description: List owners. created_at: type: - string - 'null' description: ISO 8601 creation timestamp. updated_at: type: - string - 'null' description: ISO 8601 last-updated timestamp. required: - id - name - list_type - is_public - is_archived - linked_job_id - linked_person_id - linked_organization_company_id - item_count - created_by - owners - created_at - updated_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````