> ## 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 per-tag stats with project brand metrics > Returns per-tag statistics with the project brand's visibility, ranking, sentiment, and share-of-voice metrics for a tag-level performance overview. ## OpenAPI ````yaml https://api.mentionlab.io/api/docs-json post /api/analytics/tags/stats 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/tags/stats: post: tags: - Analytics - Tags summary: Get per-tag stats with project brand metrics description: >- Returns per-tag statistics with the project brand's visibility, ranking, sentiment, and share-of-voice metrics for a tag-level performance overview. operationId: TagsController_getStats 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/TagsStatsDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/TagsStatsResponse' '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: TagsStatsDto: 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 tagType: type: string description: Which tag system to group by enum: - query - execution example: query entityIds: description: >- Entity IDs for the project brand (defaults to primary non-blacklisted) example: - 3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90 type: array items: type: string tagIds: description: Restrict to specific tag IDs (omit for all tags) example: - tag_123 - tag_456 type: array items: type: string groupIds: description: >- Tag group IDs to roll up — each selected group returns one aggregated row (deduplicated per response), as a peer of any tagIds rows. example: - 018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42 type: array items: type: string limit: type: number description: >- Max number of tags to return (top N by the active sort). Omit for all tags. example: 5 sort: description: >- Server-side sort. Allowed fields: tagName, resultCount, mentionCount, visibility, shareOfVoice, avgRanking, sentimentScore. Default: mentionCount descending. example: - field: mentionCount direction: DESC type: array items: $ref: '#/components/schemas/SortOptions' required: - tagType TagsStatsResponse: type: object properties: tags: description: >- Per-tag overview statistics with project brand metrics, one entry per tag. type: array items: $ref: '#/components/schemas/TagsStatsPoint' required: - tags 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 TagsStatsPoint: type: object properties: tagId: type: string description: Tag ID (UUID). example: 550e8400-e29b-41d4-a716-446655440000 tagName: type: string description: Tag display name. example: Pricing tagColor: type: string description: Tag color as a hex string. example: '#4f46e5' resultCount: type: number description: >- Total number of AI responses for this tag (denominator for visibility). Scoped by the request filters (project, date range, models, platforms). example: 340 projectBrand: description: >- Project brand metrics for this tag — visibility, ranking, sentiment, and share of voice for the brand within this tag's responses. allOf: - $ref: '#/components/schemas/TagsStatsProjectBrand' required: - tagId - tagName - tagColor - resultCount - projectBrand TagsStatsProjectBrand: type: object properties: mentionCount: type: number description: >- Number of AI responses (for this tag) that mention the project brand. Each AI response is counted once. example: 80 visibility: type: number description: >- Project brand visibility — how often the brand appears in responses tagged with this tag. Formula: (mentionCount / resultCount) × 100. example: 40 avgRanking: type: number description: >- Average position rank of the project brand across all mention entries for this tag. Computed across raw mention rows (not deduped). Lower values mean the brand tends to appear higher/earlier. example: 2.5 nullable: true sentimentScore: type: number description: >- Average sentiment score of the project brand mentions for this tag. Scale: 0 (most negative) to 100 (most positive). Computed across raw mention rows (not deduped). example: 72.3 shareOfVoice: type: number description: >- Share of voice — the project brand's portion of all entity mentions for this tag. Formula: (brand mentionCount / total entity mentions for this tag) × 100. The denominator includes all non-blacklisted entities, not just the brand. example: 32.1 sentimentPositive: type: number description: Number of brand mentions with positive sentiment for this tag. example: 52 sentimentNeutral: type: number description: Number of brand mentions with neutral sentiment for this tag. example: 18 sentimentNegative: type: number description: Number of brand mentions with negative sentiment for this tag. example: 10 required: - mentionCount - visibility - avgRanking - sentimentScore - shareOfVoice - sentimentPositive - sentimentNeutral - sentimentNegative ````