> ## 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. # Get a paginated page of per-theme aggregates (Brand Perception & Intelligence) > Returns ONE PAGE of the project theme taxonomy (each theme with mention count, sentiment split, average sentiment and share of total) plus a full-set summary (totals, unaffected by paging/bias) for the overview. Pass perceptionOnly=true for Brand Perception (themes from perception-type questions only) or entityId for Brand Intelligence (themes attributed to one brand). bias=praise|criticism splits positive vs negative themes. Never returns the whole taxonomy — page through it. All standard analytics filters apply. ## OpenAPI ````yaml https://api.mentionlab.io/api/docs-json post /api/analytics/themes/by-theme 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/analytics/themes/by-theme: post: tags: - Analytics - Themes summary: >- Get a paginated page of per-theme aggregates (Brand Perception & Intelligence) description: >- Returns ONE PAGE of the project theme taxonomy (each theme with mention count, sentiment split, average sentiment and share of total) plus a full-set summary (totals, unaffected by paging/bias) for the overview. Pass perceptionOnly=true for Brand Perception (themes from perception-type questions only) or entityId for Brand Intelligence (themes attributed to one brand). bias=praise|criticism splits positive vs negative themes. Never returns the whole taxonomy — page through it. All standard analytics filters apply. operationId: ThemesController_getByTheme parameters: - 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/ThemesByThemeListDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ThemesByThemeResponse' '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: ThemesByThemeListDto: type: object properties: startDate: type: string description: Start date (inclusive) example: '2025-01-01' endDate: type: string description: End date (exclusive) example: '2025-02-01' countries: description: Filter by country codes example: - BE - FR type: array items: type: string languages: description: Filter by language codes example: - en - fr type: array items: type: string models: description: Filter by AI models example: - gpt-4o - claude-3-5-sonnet type: array items: type: string queryIds: description: Filter by query IDs example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string hasSources: type: string description: >- Filter by source presence: "sources" (only with sources), "no_sources" (only without), "all" (no filter). Legacy true/false values are still accepted. enum: - all - sources - no_sources hasShopping: type: string description: >- Filter by shopping presence: "shopping" (only with shopping), "no_shopping" (only without), "all" (no filter). Legacy true/false values are still accepted. enum: - all - shopping - no_shopping queryTagIds: description: Filter by query tag IDs (numeric — bigint column) example: - '42' type: array items: type: string execTagIds: description: Filter by execution tag IDs example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string queryTagGroupIds: description: >- Filter by query tag group IDs — matches rows carrying any tag filed under a selected group. Combines with queryTagIds per queryTagMode. example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string execTagGroupIds: description: >- Filter by execution tag group IDs — matches rows carrying any tag filed under a selected group. Combines with execTagIds per execTagMode. example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string queryTypes: type: array description: >- Filter by query type. Include "untyped" to also match queries without a type. Results from since-deleted queries are excluded when this filter is set. items: type: string enum: - comparative - informative - perception - untyped queryTagMode: type: string description: >- Query tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags. enum: - and - or default: or execTagMode: type: string description: >- Execution tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags. enum: - and - or default: or timezone: type: string description: >- IANA timezone for date bucketing and filtering (e.g. "Europe/Brussels"). Defaults to UTC. example: Europe/Brussels default: UTC groupBy: type: string description: >- Row grouping level for entity results. "none" = one row per entity, "division" = one row per division (entities not in a division get their own row), "group" = one row per top-level group (divisions roll up into their group). Defaults to "none". enum: - none - division - group groupByEntityGroup: type: boolean description: >- Deprecated — use groupBy instead. true is equivalent to groupBy="group". deprecated: true example: false showAllEntities: type: boolean description: >- Include entities that have only ever been seen in a single AI response. These are mostly one-off extraction noise and are hidden by default. example: false entityId: type: string description: >- Restrict to themes attributed to a specific entity (brand) — used by Brand Intelligence. Omit for all themes. example: 550e8400-e29b-41d4-a716-446655440000 perceptionOnly: type: boolean description: >- Only themes from perception-type questions (queries.type='perception') — used by Brand Perception (MLENG-357). Combinable with entityId to scope a perception view to one brand. example: true page: type: number description: 'Page number (1-based). Default: 1.' example: 1 pageSize: type: number description: 'Results per page. Default: 20, max: 100.' example: 20 bias: type: string description: >- Restrict to predominantly-positive ('praise') or predominantly-negative ('criticism') themes. Omit for all themes ranked by frequency. enum: - praise - criticism ThemesByThemeResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/ThemePoint' page: $ref: '#/components/schemas/Paging' summary: $ref: '#/components/schemas/ThemeSummary' required: - items - page - summary 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 ThemePoint: type: object properties: themeId: type: string description: Canonical theme ID. label: type: string description: Frozen theme label (or the surface phrase while provisional). example: Battery Life status: type: string description: Theme status. enum: - provisional - stable example: stable memberCount: type: number description: Number of distinct member phrases in the theme. example: 7 mentionCount: type: number description: Total mentions of this theme. example: 42 sentimentScore: type: number description: Average sentiment score (1–100) across the mentions. example: 72 positive: type: number description: Count of positive-sentiment mentions. neutral: type: number description: Count of neutral-sentiment mentions. negative: type: number description: Count of negative-sentiment mentions. sharePct: type: number description: >- Share of the full filtered set of mentions (%), 1 decimal — a biased (praise/criticism) page can sum to <100%. example: 12.4 required: - themeId - label - status - memberCount - mentionCount - sentimentScore - positive - neutral - negative - sharePct 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 ThemeSummary: type: object properties: themeCount: type: number description: Distinct themes in scope. mentionCount: type: number description: Total theme mentions in scope. positive: type: number description: Positive-sentiment mentions. neutral: type: number description: Neutral-sentiment mentions. negative: type: number description: Negative-sentiment mentions. sentimentScore: type: number description: Mention-weighted average sentiment (1–100). required: - themeCount - mentionCount - positive - neutral - negative - sentimentScore ````