> ## Documentation Index > Fetch the complete documentation index at: https://docs.mentionlab.io/llms.txt > Use this file to discover all available pages before exploring further. # List entities with filters > Returns a paginated list of entities, excluding merged entities by default, with filtering and sorting options. ## OpenAPI ````yaml https://api.mentionlab.io/api/docs-json post /api/entities/list openapi: 3.0.0 info: title: MentionLab Public API v0.3.4-rc description: '' version: 0.3.4-rc contact: {} servers: - url: https://api.mentionlab.io security: [] tags: [] paths: /api/entities/list: post: tags: - Entities summary: List entities with filters description: >- Returns a paginated list of entities, excluding merged entities by default, with filtering and sorting options. operationId: EntitiesRefController_list parameters: - name: limit required: false in: query schema: type: integer minimum: 1 maximum: 100 default: 50 - name: page required: false in: query schema: type: integer minimum: 1 default: 1 - name: x-project-id in: header description: Project ID to specify the project context required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ListEntitiesDto' responses: '200': description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/PagingResponse' properties: results: type: array items: $ref: '#/components/schemas/EntityResponse' page: $ref: '#/components/schemas/Paging' '400': description: >- The request failed validation — the body, query or path parameters are malformed or out of range. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: The request is missing valid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: >- The authenticated principal lacks the required permission, or access to the requested organisation/project. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' components: schemas: ListEntitiesDto: type: object properties: name: type: string description: Filter entities by name using a case-insensitive partial match. example: Acme type: type: string description: Filter entities by their exact type. example: brand isOwned: type: boolean description: Filter entities by whether they are owned by the current project. example: true isPrimary: type: boolean description: Filter entities by whether they are marked as primary. example: true isCompetitor: type: boolean description: Filter entities by whether they are flagged as competitors. example: false isBlacklisted: type: boolean description: Filter entities by whether they are blacklisted. example: false isRecurring: type: boolean description: >- Filter entities by whether they have been seen in more than one AI response. Pass `true` to hide one-off extractions. example: true groupId: type: string description: >- Filter entities attached to a specific container (group or division), by its ID. Exact-node: a group ID does not include entities in its divisions — use rootGroupId for that. example: 018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42 rootGroupId: type: string description: >- Filter entities under a top-level group, INCLUDING entities in its divisions. example: 018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42 sort: description: >- Sort criteria for the entity list. Each item targets a sortable field (name, isPrimary, isOwned, isCompetitor, isBlacklisted, createdAt, updatedAt) with an ASC or DESC direction. Defaults to sorting by name ascending. example: - field: name direction: ASC type: array items: $ref: '#/components/schemas/SortOptions' PagingResponse: type: object properties: page: $ref: '#/components/schemas/Paging' required: - page EntityResponse: type: object properties: id: type: string format: uuid name: type: string slug: type: string type: type: string enum: - brand - person - company - other isOwned: type: boolean isPrimary: type: boolean isCompetitor: type: boolean isBlacklisted: type: boolean group: $ref: '#/components/schemas/EntityGroupRef' domains: description: Domains mapped to this entity (project-scoped). type: array items: $ref: '#/components/schemas/EntityDomainRef' canonicalId: type: string format: uuid createdAt: format: date-time type: string updatedAt: format: date-time type: string required: - id - name - slug - type - isOwned - isPrimary - isCompetitor - isBlacklisted - domains - createdAt - updatedAt Paging: type: object properties: totalRecords: type: number limit: type: number currentPage: type: number totalPages: type: number nextPage: type: number prevPage: type: number required: - totalRecords - limit - currentPage - totalPages - nextPage - prevPage ApiErrorResponse: type: object properties: statusCode: type: number description: HTTP status code of the error. example: 400 message: type: string description: >- Human-readable description of the error. Validation failures return an array of per-field validation errors instead of a single string. example: Validation failed error: type: string description: Short name of the HTTP error. example: Bad Request required: - statusCode SortOptions: type: object properties: field: type: string description: Field name to sort by direction: type: string enum: - ASC - DESC description: Sort direction required: - field - direction EntityGroupRef: type: object properties: id: type: string format: uuid kind: type: string enum: - group - division description: Whether this container is a top-level group or a division. parent: type: string description: >- Parent group ID when this container is a division inside a group; null for top-level groups and standalone divisions. Lets the entity list render "Group › Division" without a second fetch. format: uuid nullable: true name: type: string slug: type: string required: - id - kind - name - slug EntityDomainRef: type: object properties: id: type: string format: uuid description: The entity-domain mapping id. domain: type: string example: hubspot.com description: The mapped root domain. required: - id - domain ````