{"openapi":"3.0.0","paths":{"/api/projects/{id}":{"get":{"description":"Returns a single project by its identifier; the path id must match the project header or the request is rejected.","operationId":"ProjectsController_getById","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the project to retrieve.","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectResponse"}}}},"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"}}}}},"summary":"Get a project","tags":["Projects"],"x-public-api":true},"delete":{"description":"Deletes the project identified by the path id; the path id must match the project header or the request is rejected.","operationId":"ProjectsController_delete","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the project to delete.","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Delete a project","tags":["Projects"],"x-public-api":true}},"/api/v1/projects":{"get":{"description":"Returns a paginated list of projects the user or organisation can access, optionally filtered by name.","operationId":"ProjectsV1Controller_list_v1","parameters":[{"name":"scope","required":false,"in":"query","description":"Scope of the projects to list. Can be \"user\" or \"org\".","schema":{"type":"string"}},{"name":"name","required":false,"in":"query","description":"Filter projects by name (substring match).","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":250,"default":50}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagingResponse"}],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ProjectResponse"}},"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"}}}}},"summary":"List projects of the organisation","tags":["Projects"],"x-public-api":true}},"/api/v1/projects/{id}":{"patch":{"description":"Updates a project's editable fields; the path `id` must match the `x-project-id` header.","operationId":"ProjectsV1Controller_update_v1","parameters":[{"name":"id","required":true,"in":"path","description":"Identifier of the project to update. Must match the `x-project-id` header.","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"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/UpdateProjectDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Update a project","tags":["Projects"],"x-public-api":true}},"/api/v1/projects/{id}/settings":{"patch":{"description":"Replaces the project's free-form settings blob (e.g. saved custom filters) with the supplied object. The FE owns the full object, so add/edit/remove are all this one call. Path `id` must match the `x-project-id` header.","operationId":"ProjectsV1Controller_updateSettings_v1","parameters":[{"name":"id","required":true,"in":"path","description":"Identifier of the project to update. Must match the `x-project-id` header.","schema":{"example":"550e8400-e29b-41d4-a716-446655440000","type":"string"}},{"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/ProjectSettingsDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Update project settings","tags":["Projects"],"x-public-api":true}},"/api/queries/many":{"post":{"description":"Creates (upserts) several queries at once along with their tag associations; all referenced tag IDs are validated against the project first.","operationId":"QueriesController_createMany","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/CreateManyQueriesDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/QueryResponse"}}}}},"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"}}}}},"summary":"Create queries","tags":["Queries"],"x-public-api":true}},"/api/queries/many/tags-only":{"patch":{"description":"Replaces the tag associations of existing queries matched by their text, language and country rather than by id; only the tags are changed.","operationId":"QueriesController_updateManyTags","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/CreateManyQueriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/QueryResponse"}}}}},"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"}}}}},"summary":"Bulk-update tag associations for queries matched by text/language/country","tags":["Queries"],"x-public-api":true}},"/api/queries/list":{"post":{"description":"Returns a paginated list of the project's queries, applying the filters and sorting from the request body; each result includes its tag IDs.","operationId":"QueriesController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"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/ListQueryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagingResponse"}],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/QueryResponse"}},"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"}}}}},"summary":"Get all queries","tags":["Queries"],"x-public-api":true}},"/api/queries/count":{"get":{"description":"Returns the total number of queries in the project.","operationId":"QueriesController_count","parameters":[{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"number"}}}},"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"}}}}},"summary":"Get total query count for a project","tags":["Queries"],"x-public-api":true}},"/api/queries/{id}":{"get":{"description":"Returns a single query with its tags by UUID; a query belonging to another project is treated as not found.","operationId":"QueriesController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the query to retrieve.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"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"}}}}},"summary":"Get a query by ID","tags":["Queries"],"x-public-api":true},"delete":{"description":"Deletes the query. Previously generated results and responses are kept but unlinked from the query.","operationId":"QueriesController_remove","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the query to delete.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"The query was deleted. Related results and responses are retained but no longer linked to it."},"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"}}}}},"summary":"Delete a query","tags":["Queries"],"x-public-api":true},"patch":{"description":"Updates a query by UUID to change its type and/or replace its tag associations; the supplied tag IDs are validated against the project.","operationId":"QueriesController_update","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the query to update.","schema":{"format":"uuid","type":"string"}},{"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/UpdateQueryDto"}}}},"responses":{"204":{"description":"The query was updated successfully."},"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"}}}}},"summary":"Update a query's type or tag associations","tags":["Queries"],"x-public-api":true}},"/api/v1/projects/{id}/locales":{"get":{"description":"Which locales this project uses. `source=runs` (default) = locales from real executions; `source=config` = the configured queries allowlist (may include never-run locales). Answers a different question than POST /api/v1/analytics/facets, which reports window-scoped, selection-aware availability: this endpoint is the project's full locale history/config.","operationId":"ProjectLocalesV1Controller_getLocales_v1","parameters":[{"name":"id","required":true,"in":"path","description":"UUID of the project whose used locales are requested. Must match the x-project-id header.","schema":{"format":"uuid","type":"string"}},{"name":"source","required":false,"in":"query","description":"Which locales to return: 'runs' (default) for locales from real executions, or 'config' for the configured queries allowlist.","schema":{"$ref":"#/components/schemas/LocaleSource"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryLocalesResponse"}}}},"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"}}}}},"summary":"Countries and languages of a project’s locales","tags":["Projects"],"x-public-api":true}},"/api/analytics/visibility/entities":{"post":{"description":"Returns aggregated visibility metrics per entity over the selected date range, sorted by visibility descending, suitable for a leaderboard or comparison table.","operationId":"VisibilityController_getEntities","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/VisibilityEntitiesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityEntityPoint"}}}}},"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"}}}}},"summary":"Get per-entity visibility scores","tags":["Analytics - Visibility"],"x-public-api":true}},"/api/analytics/visibility/share-of-voice":{"post":{"description":"Returns each entity's share of voice (its percentage of total brand mentions) over the selected date range, sorted by mention count descending, for comparing against competitors.","operationId":"VisibilityController_getShareOfVoice","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/ShareOfVoiceDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareOfVoiceResponse"}}}},"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"}}}}},"summary":"Get brand share of voice","tags":["Analytics - Visibility"],"x-public-api":true}},"/api/analytics/tags/summary":{"post":{"description":"Returns per-tag visibility for the selected entities, with totals and average position rank, to compare brand visibility across query topics.","operationId":"TagsController_getSummary","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/TagsSummaryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagsSummaryPoint"}}}}},"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"}}}}},"summary":"Get per-tag visibility summary","tags":["Analytics - Tags"],"x-public-api":true}},"/api/analytics/tags/matrix":{"post":{"description":"Returns a time-bucketed visibility matrix with one point per tag per bucket, to chart how tag visibility trends over time.","operationId":"TagsController_getMatrix","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/TagsMatrixDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagsMatrixPoint"}}}}},"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"}}}}},"summary":"Get per-tag visibility timeseries matrix","tags":["Analytics - Tags"],"x-public-api":true}},"/api/analytics/tags/stats":{"post":{"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"}}}}},"summary":"Get per-tag stats with project brand metrics","tags":["Analytics - Tags"],"x-public-api":true}},"/api/analytics/tags/models":{"post":{"description":"Returns a paginated list of tags ranked by project brand visibility, each with a per-model visibility breakdown; narrow to specific tags with `tagIds`.","operationId":"TagsController_getModels","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/TagsModelsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagsModelsResponse"}}}},"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"}}}}},"summary":"Get per-tag brand visibility broken down by model","tags":["Analytics - Tags"],"x-public-api":true}},"/api/analytics/tags/sources":{"post":{"description":"Returns the top cited source domains for a tag with citation and reach metrics, showing which websites AI models cite most for that topic.","operationId":"TagsController_getSources","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/TagSourcesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagSourcesResponse"}}}},"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"}}}}},"summary":"Get citation sources for a specific tag","tags":["Analytics - Tags"],"x-public-api":true}},"/api/analytics/tags/trends":{"post":{"description":"Returns time-bucketed brand mention count and visibility per tag, to track how the project brand's visibility trends within each topic over time.","operationId":"TagsController_getTrends","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/TagsTrendsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagsTrendsPoint"}}}}},"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"}}}}},"summary":"Get per-tag brand visibility over time","tags":["Analytics - Tags"],"x-public-api":true}},"/api/analytics/sources/domain-reach":{"post":{"description":"Returns the project's cited source domains, each with its citation rate, cited page count and the share of those pages that also mention the brand; limited by `size` (default 15, max 50).","operationId":"SourcesController_getDomainReach","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/SourceDomainReachDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDomainReachResponse"}}}},"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"}}}}},"summary":"Per-domain citation rate and brand true reach","tags":["Analytics - Sources"],"x-public-api":true}},"/api/analytics/sources/tld-breakdown":{"post":{"description":"Groups source citations by the ICANN public suffix of the cited domain (e.g. \"be\", \"co.uk\", \"com\"), with citationShare and citationRate per TLD. Useful for slicing sources by country / ccTLD.","operationId":"SourcesController_getTldBreakdown","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/SourceTldBreakdownDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceTldBreakdownResponse"}}}},"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"}}}}},"summary":"Citation breakdown by ICANN public suffix (TLD)","tags":["Analytics - Sources"],"x-public-api":true}},"/api/analytics/shopping/overview":{"post":{"description":"Returns headline shopping analytics over the selected date range: shopping coverage (the share of AI responses with shopping results) plus distinct brand, product and merchant counts.","operationId":"ShoppingController_getOverview","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/ShoppingOverviewDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShoppingOverviewResponse"}}}},"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"}}}}},"summary":"Shopping overview stats","tags":["Analytics - Shopping"],"x-public-api":true}},"/api/analytics/shopping/visibility-timeseries":{"post":{"description":"Returns a time-bucketed series of brand visibility within shopping results over the selected date range; when no entities are supplied the project's primary entities are used.","operationId":"ShoppingController_getVisibilityTimeseries","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/ShoppingVisibilityTimeseriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShoppingVisibilityTimeseriesResponse"}}}},"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"}}}}},"summary":"Brand visibility in shopping results over time","tags":["Analytics - Shopping"],"x-public-api":true}},"/api/analytics/shopping/merchants/{merchantId}/products":{"post":{"description":"Returns products sold by this merchant with prices, ratings, and share.","operationId":"ShoppingController_getMerchantProducts","parameters":[{"name":"merchantId","required":true,"in":"path","description":"UUID of the merchant whose products should be listed.","schema":{"example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","type":"string"}},{"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/ShoppingMerchantProductsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShoppingMerchantProductsResponse"}}}},"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"}}}}},"summary":"List products for a merchant","tags":["Analytics - Shopping"],"x-public-api":true}},"/api/analytics/sentiment/overview":{"post":{"description":"Returns the project brand's overall sentiment over the filtered mentions: average score (0-100), derived label, total mentions, and positive/neutral/negative counts.","operationId":"SentimentController_getOverview","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/SentimentOverviewDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentOverviewResponse"}}}},"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"}}}}},"summary":"Get overall sentiment for project brand","tags":["Analytics - Sentiment"],"x-public-api":true}},"/api/analytics/sentiment/timeseries":{"post":{"description":"Returns the project brand's sentiment over time, one point per bucket in chronological order with its average score, positive/neutral/negative mention counts and presentIn (distinct AI responses). mentionCount is deprecated and mirrors presentIn until it is removed.","operationId":"SentimentController_getTimeseries","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/SentimentTimeseriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SentimentTimeseriesPoint"}}}}},"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"}}}}},"summary":"Get sentiment over time","tags":["Analytics - Sentiment"],"x-public-api":true}},"/api/analytics/sentiment/by-entity":{"post":{"description":"Returns sentiment per entity (optionally grouped), sorted by mention count descending.","operationId":"SentimentController_getByEntity","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/SentimentByEntityDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SentimentByEntityPoint"}}}}},"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"}}}}},"summary":"Get sentiment comparison across entities","tags":["Analytics - Sentiment"],"x-public-api":true}},"/api/analytics/queries/{queryId}/sources":{"post":{"description":"Returns the source domains cited in AI responses for a single query with their citation metrics, ordered by citation count; the body filters by date range, models and tags.","operationId":"QueriesStatsController_getQuerySources","parameters":[{"name":"queryId","required":true,"in":"path","description":"UUID of the query to retrieve cited source domains for.","schema":{"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"string"}},{"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/QueryDetailDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryDetailSourcesResponse"}}}},"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"}}}}},"summary":"Get source domains for a single query","tags":["Analytics - Queries"],"x-public-api":true}},"/api/analytics/queries/{queryId}/entities":{"post":{"description":"Returns the entities detected for a single query (brand, competitors and others) with visibility, share of voice, ranking and sentiment, ordered by presence; the body filters by date range, models, entity types and tags.","operationId":"QueriesStatsController_getQueryEntities","parameters":[{"name":"queryId","required":true,"in":"path","description":"UUID of the query to retrieve detected entity stats for.","schema":{"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"string"}},{"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/QueryDetailDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryDetailEntitiesResponse"}}}},"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"}}}}},"summary":"Get entity stats for a single query","tags":["Analytics - Queries"],"x-public-api":true}},"/api/analytics/queries/{queryId}/sources-by-model":{"post":{"description":"Returns the top 5 cited source domains for each AI model that answered the query, to compare which sources different models prefer; the body filters by date range, models and tags.","operationId":"QueriesStatsController_getQuerySourcesByModel","parameters":[{"name":"queryId","required":true,"in":"path","description":"UUID of the query to retrieve top cited sources grouped by AI model for.","schema":{"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"string"}},{"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/QueryDetailDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryDetailSourcesByModelResponse"}}}},"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"}}}}},"summary":"Get top sources grouped by model for a single query","tags":["Analytics - Queries"],"x-public-api":true}},"/api/analytics/queries/{queryId}/results":{"post":{"description":"Returns a paginated list of the individual AI responses for a single query, including the response text, model, citations and mentioned entities; the body filters by date range, models and tags.","operationId":"QueriesStatsController_getQueryResults","parameters":[{"name":"queryId","required":true,"in":"path","description":"UUID of the query to list individual AI responses for.","schema":{"example":"3fa85f64-5717-4562-b3fc-2c963f66afa6","type":"string"}},{"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/QueryResultsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryDetailResultsResponse"}}}},"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"}}}}},"summary":"List AI responses for a query","tags":["Analytics - Queries"],"x-public-api":true}},"/api/analytics/models/entity-visibility":{"post":{"description":"Returns a matrix of entities by AI model where each cell is the percentage of that model's responses that mention the entity; use `entityTypes` to limit which entities are included.","operationId":"ModelsController_getEntityVisibility","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/ModelsFilterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityVisibilityResponse"}}}},"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"}}}}},"summary":"Get entity visibility breakdown per AI model","tags":["Analytics - Models"],"x-public-api":true}},"/api/analytics/models/platform-details":{"post":{"description":"Returns one row per AI model summarising the selected entities' visibility, average ranking, mention count and share of voice, ordered by total responses descending.","operationId":"ModelsController_getPlatformDetails","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/ModelsFilterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformDetailsResponse"}}}},"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"}}}}},"summary":"Get platform details (visibility, ranking, share of voice) per AI model","tags":["Analytics - Models"],"x-public-api":true}},"/api/analytics/models/drill-down/entities":{"post":{"description":"Drills into a single AI model and returns every detected entity with its visibility, share of voice, mention count and average ranking, ordered by visibility descending.","operationId":"ModelsController_getDrilldownEntities","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/ModelsDrilldownDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrilldownEntitiesResponse"}}}},"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"}}}}},"summary":"Get top entities for a specific AI model","tags":["Analytics - Models"],"x-public-api":true}},"/api/analytics/models/drill-down/sources":{"post":{"description":"Drills into a single AI model and returns its most cited source domains with their result count, citation rate and page count, ordered by result count descending.","operationId":"ModelsController_getDrilldownSources","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/ModelsDrilldownDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrilldownSourcesResponse"}}}},"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"}}}}},"summary":"Get top sources for a specific AI model","tags":["Analytics - Models"],"x-public-api":true}},"/api/analytics/themes/super-themes":{"post":{"description":"Returns the mutable top grouping: each super-theme (a box) with its member themes, every theme carrying mention count + sentiment so the UI can colour the chips. Super-theme sentiment is the mention-weighted average of its themes. All standard analytics filters apply.","operationId":"ThemesController_getSuperThemes","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/ThemesByThemeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SuperThemePoint"}}}}},"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"}}}}},"summary":"Get super-themes with their member themes (Brand Intelligence)","tags":["Analytics - Themes"],"x-public-api":true}},"/api/analytics/themes/by-theme":{"post":{"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"}}}}},"summary":"Get a paginated page of per-theme aggregates (Brand Perception & Intelligence)","tags":["Analytics - Themes"],"x-public-api":true}},"/api/analytics/themes/stance-distribution":{"post":{"description":"Returns each brand mentioned in scope with its stance distribution (chosen / mentioned / named / negative_mentioned / negative_named) from EntityMentions.stance, plus total mentions for ranking. The five buckets are exclusive. Pass entityId to narrow to one brand. All standard analytics filters apply.","operationId":"ThemesController_getStanceDistribution","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/StanceDistributionDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StancePoint"}}}}},"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"}}}}},"summary":"Get per-brand stance distribution (Brand Intelligence)","tags":["Analytics - Themes"],"x-public-api":true}},"/api/analytics/themes/theme-entity-matrix":{"post":{"description":"One cell per (canonical theme, brand) with mention count and sentiment split, over brand-attributed theme mentions across all questions. The client pivots these into a themes-rows × brands-columns grid. All standard analytics filters apply.","operationId":"ThemesController_getThemeEntityMatrix","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/ThemesByThemeDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ThemeEntityCell"}}}}},"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"}}}}},"summary":"Get the theme × brand sentiment matrix (Brand Intelligence)","tags":["Analytics - Themes"],"x-public-api":true}},"/api/analytics/themes/mentions":{"post":{"description":"Returns the individual theme_mentions behind one canonical theme — each with its verbatim evidence span, sentiment, strength and a link to the source AI response. Pass entityId to scope to one brand, sentiment to filter. Paginated, central/supporting first then most recent. All standard analytics filters apply.","operationId":"ThemesController_getThemeMentions","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/ThemeMentionsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThemeMentionsResponse"}}}},"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"}}}}},"summary":"Drill into a theme: its individual mentions with evidence spans","tags":["Analytics - Themes"],"x-public-api":true}},"/api/analytics/themes/entity-responses":{"post":{"description":"Returns the AI responses where one brand earned a given stance (e.g. negative_mentioned), each with its full text and the brand’s theme evidence inside it (the why). entityId is expanded to its merge family. Paginated, most recent first. All standard analytics filters apply.","operationId":"ThemesController_getEntityStanceResponses","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/EntityStanceDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityStanceResponse"}}}},"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"}}}}},"summary":"Drill into a brand stance: the AI responses where it was chosen/negatively mentioned/…","tags":["Analytics - Themes"],"x-public-api":true}},"/api/analytics/themes/response":{"post":{"description":"Returns the full text + minimal context of a single AI response (project-scoped) so a drill-down can highlight an evidence span in its original answer.","operationId":"ThemesController_getResponseText","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/ResponseTextDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseTextResponse"}}}},"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"}}}}},"summary":"Fetch one AI response’s full text (for the in-context evidence viewer)","tags":["Analytics - Themes"],"x-public-api":true}},"/api/analytics/ads/brands":{"post":{"description":"Returns each advertised brand's share of sponsored ad placements (its ad cards over all ad cards in scope), with the ad rate and response totals for the filtered scope; honors the active filters.","operationId":"ChatgptAdsController_getBrands","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/ChatgptAdsFilterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatgptAdsBrandsResponse"}}}},"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"}}}}},"summary":"Get per-brand ad share","tags":["Analytics - Ads"],"x-public-api":true}},"/api/analytics/ads/formats":{"post":{"description":"Returns the share of sponsored ad placements per card format (provider-defined open set, e.g. 'product_card_v2', 'image_card_v2'); honors the active filters.","operationId":"ChatgptAdsController_getFormats","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/ChatgptAdsFilterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatgptAdsFormatsResponse"}}}},"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"}}}}},"summary":"Get ad placement mix by card format","tags":["Analytics - Ads"],"x-public-api":true}},"/api/analytics/ads/advertisers":{"post":{"description":"Returns each advertiser's share of sponsored ad placements (who paid for the slot, often a retailer; raw provider labels, never entity-resolved), with the ad rate and response totals for the filtered scope; honors the active filters.","operationId":"ChatgptAdsController_getAdvertisers","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/ChatgptAdsFilterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatgptAdsAdvertisersResponse"}}}},"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"}}}}},"summary":"Get per-advertiser ad share","tags":["Analytics - Ads"],"x-public-api":true}},"/api/entities":{"post":{"description":"Creates a new entity (brand, person, company, or other) in the project, automatically generating a default alias from its name.","operationId":"EntitiesRefController_create","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/CreateEntityDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityResponse"}}}},"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"}}}}},"summary":"Create a new entity","tags":["Entities"],"x-public-api":true}},"/api/entities/{id}":{"get":{"description":"Returns the full detail for a single entity, including its group, its aliases, and any entities merged into it.","operationId":"EntitiesRefController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the entity to retrieve.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityDetailResponse"}}}},"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"}}}}},"summary":"Get entity by ID","tags":["Entities"],"x-public-api":true},"delete":{"description":"Permanently deletes an entity and its aliases; fails if it is still referenced, so blacklist it instead to hide it while keeping historical data.","operationId":"EntitiesRefController_delete","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the entity to delete.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Delete an entity","tags":["Entities"],"x-public-api":true},"patch":{"description":"Partially updates an entity's name, type, classification flags and group; setting the group to null removes it from its group. Renaming also regenerates the slug and adds the new name as an alias, keeping the old one so past mentions still resolve.","operationId":"EntitiesRefController_update","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the entity to update.","schema":{"format":"uuid","type":"string"}},{"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/UpdateEntityDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Update an entity","tags":["Entities"],"x-public-api":true}},"/api/entities/list":{"post":{"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"}}}}},"summary":"List entities with filters","tags":["Entities"],"x-public-api":true}},"/api/entities/many":{"patch":{"description":"Updates classification flags on several entities at once; only the flags provided are changed, and the call is rejected when none are supplied.","operationId":"EntitiesRefController_bulkUpdate","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/BulkUpdateEntitiesDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Bulk update classification flags on multiple entities","tags":["Entities"],"x-public-api":true}},"/api/entities/recompute-relationships":{"post":{"description":"Recomputes each cited source domain's relationship (owned / competitor / partner_affiliate; absence ⇒ independent) for the project from the current entity-domain mappings; a manual trigger to run after editing owned/competitor/partner entities or their domains.","operationId":"EntitiesRefController_recomputeRelationships","parameters":[{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecomputeRelationshipsResultResponse"}}}},"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"}}}}},"summary":"Recompute the project-scoped source-domain relationships","tags":["Entities"],"x-public-api":true}},"/api/entities/import":{"post":{"description":"Creates or updates a batch of rows in one transaction, matching each by `id` or by name; omitted fields are left unchanged and aliases are only ever added. Use dryRun to preview the per-row outcome, and POST /entities/import/merge afterwards for the mergedIntoId column.","operationId":"EntitiesRefController_importEntities","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/ImportEntitiesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportEntitiesResponse"}}}},"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"}}}}},"summary":"Import entities from a spreadsheet (create and update)","tags":["Entities"],"x-public-api":true}},"/api/entities/import/merge":{"post":{"description":"Applies the `mergedIntoId` column of an entity import, merging each entity into the one its id names. Send the whole file in one request: chains and cycles are resolved across the entire edge set, so a partial batch resolves differently. Bad edges fail their own row and leave the rest to apply.","operationId":"EntitiesRefController_importMerges","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/ImportMergeEntitiesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportMergeEntitiesResponse"}}}},"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"}}}}},"summary":"Merge entities in bulk from a spreadsheet","tags":["Entities"],"x-public-api":true}},"/api/entities/{id}/aliases":{"post":{"description":"Adds a new alias to the entity; aliases are unique per project, so adding one that already exists returns 409 Conflict.","operationId":"EntitiesRefController_addAlias","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the entity to add the alias to.","schema":{"format":"uuid","type":"string"}},{"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/AddAliasDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityAliasResponse"}}}},"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"}}}}},"summary":"Add an alias to an entity","tags":["Entities"],"x-public-api":true}},"/api/entities/{id}/aliases/{aliasId}":{"delete":{"description":"Removes an alias from the entity; an entity must keep at least one alias, so removing the last remaining one returns 400.","operationId":"EntitiesRefController_removeAlias","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the entity the alias belongs to.","schema":{"format":"uuid","type":"string"}},{"name":"aliasId","required":true,"in":"path","description":"The UUID of the alias to remove.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Remove an alias from an entity","tags":["Entities"],"x-public-api":true}},"/api/entities/merge":{"post":{"description":"Merges the source entities into the target so they report under it in analytics; the merge can be reversed via the unmerge endpoint, though conflicting alias variants dropped during the merge are not restored.","operationId":"EntitiesRefController_merge","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/MergeEntitiesDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Merge entities into a target","tags":["Entities"],"x-public-api":true}},"/api/entities/unmerge":{"post":{"description":"Makes previously merged entities independent again, named either directly with `ids` or by survivor with `survivorIds` to release everything merged into them. Ids that are not currently merged are skipped, so the same list can be re-sent safely.","operationId":"EntitiesRefController_bulkUnmerge","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/BulkUnmergeEntitiesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUnmergeEntitiesResponse"}}}},"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"}}}}},"summary":"Unmerge entities in bulk","tags":["Entities"],"x-public-api":true}},"/api/entities/{id}/unmerge":{"post":{"description":"Reverses a merge, making the entity independent again; only works on entities that were previously merged.","operationId":"EntitiesRefController_unmerge","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the merged entity to unmerge.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Unmerge a previously merged entity","tags":["Entities"],"x-public-api":true}},"/api/organisations":{"get":{"description":"Lists every organisation the current user can access, directly as a member or indirectly through membership of one of its projects.","operationId":"OrganisationsController_list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrganisationResponseWithIndirect"}}}}},"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"}}}}},"summary":"Get organisations for the current user","tags":["Organisations"],"x-public-api":true}},"/api/jobs/trigger":{"post":{"description":"Runs every query in the project against the selected AI models for the requested number of executions, charging the required credits up front; returns null when the project has no queries.","operationId":"JobsController_createFromProjectQueries","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/CreateFromProjectQueriesDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"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"}}}}},"summary":"Trigger an execution for all project queries","tags":["Jobs"],"x-public-api":true}},"/api/jobs/{id}":{"get":{"description":"Retrieves a single job by its ID within the project.","operationId":"JobsController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the job to retrieve.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"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"}}}}},"summary":"Get a job by ID","tags":["Jobs"],"x-public-api":true}},"/api/jobs/list":{"post":{"description":"Returns a paginated list of jobs for the project, applying the filtering and sorting from the request body and including each job creating user.","operationId":"JobsController_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/ListJobsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagingResponse"}],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/JobResponse"}},"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"}}}}},"summary":"List jobs","tags":["Jobs"],"x-public-api":true}},"/api/v1/projects/{id}/last-execution-date":{"get":{"description":"Returns the date of the project's most recent job execution as a data-freshness indicator, or `null` if it has never run a job.","operationId":"ProjectLastExecutionV1Controller_getLastExecutionDate_v1","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier (UUID) of the project to read the last execution date for. Must match the `x-project-id` header.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobLastExecutionDateResponse"}}}},"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"}}}}},"summary":"Last job execution date for a project","tags":["Projects"],"x-public-api":true}},"/api/v1/projects/{id}/models":{"get":{"description":"Returns the distinct AI models that have been run for the project, including models whose runs are still pending or failed; the path `id` must match the `x-project-id` header.","operationId":"ProjectModelsV1Controller_getProjectModels_v1","parameters":[{"name":"id","required":true,"in":"path","description":"The project identifier; must match the `x-project-id` header.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JenModelsResponse"}}}},"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"}}}}},"summary":"Distinct AI models used in a project","tags":["Projects"],"x-public-api":true}},"/api/v1/job-executions/{id}":{"get":{"description":"Returns the full detail of one run — its AI response citations, mentioned entities with sentiment and run metadata; a run with no stored response (pending or failed) is treated as not found.","operationId":"JobExecutionsV1Controller_getDetail_v1","parameters":[{"name":"id","required":true,"in":"path","description":"The job execution id (`jobExecutionId`, UUID) of the run to fetch.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobExecutionDetailResponse"}}}},"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"}}}}},"summary":"Get full detail for a single run","tags":["Job Executions"],"x-public-api":true}},"/api/tags/many":{"post":{"description":"Creates several tags at once and returns the newly created tags.","operationId":"TagsController_createMany","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/CreateManyTagsDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagResponse"}}}}},"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"}}}}},"summary":"Create multiple tags","tags":["Tags"],"x-public-api":true}},"/api/tags/list":{"post":{"description":"Returns a paginated list of tags matching the supplied filters, optionally with the linked-query count per tag.","operationId":"TagsController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"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/ListTagDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagingResponse"}],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/TagResponse"}},"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"}}}}},"summary":"List tags","tags":["Tags"],"x-public-api":true}},"/api/tags/{id}":{"get":{"description":"Returns a single tag by its id.","operationId":"TagsController_getOne","parameters":[{"name":"id","required":true,"in":"path","description":"The numeric identifier of the tag to retrieve.","schema":{"type":"number"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagResponse"}}}},"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"}}}}},"summary":"Get a tag","tags":["Tags"],"x-public-api":true},"delete":{"description":"Permanently deletes the tag.","operationId":"TagsController_remove","parameters":[{"name":"id","required":true,"in":"path","description":"The numeric identifier of the tag to delete.","schema":{"type":"number"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Delete a tag","tags":["Tags"],"x-public-api":true},"patch":{"description":"Updates the name, color and/or group of a tag. Send groupId null to ungroup.","operationId":"TagsController_update","parameters":[{"name":"id","required":true,"in":"path","description":"The numeric identifier of the tag to update.","schema":{"type":"number"}},{"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/UpdateTagDto"}}}},"responses":{"204":{"description":"The tag was updated successfully."},"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"}}}}},"summary":"Update a tag","tags":["Tags"],"x-public-api":true}},"/api/tags/bulk/group":{"post":{"description":"Files every tag in the selection (either explicit ids, or all tags matching a filter except the excluded ids) under the given tag group node, or ungroups them when groupId is null. Never triggers tag re-matching.","operationId":"TagsController_bulkMoveToGroup","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/BulkGroupTagsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkActionResponse"}}}},"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"}}}}},"summary":"Move a selection of tags to a group","tags":["Tags"],"x-public-api":true}},"/api/tags/link/many":{"post":{"description":"Associates every supplied tag with every supplied query, skipping links that already exist.","operationId":"TagsController_linkManyToQueries","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/LinkManyTagsDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Link tags to queries","tags":["Tags"],"x-public-api":true}},"/api/tags/unlink/many":{"post":{"description":"Removes the association between every supplied tag and every supplied query.","operationId":"TagsController_unlinkManyFromQueries","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/UnlinkManyTagsDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Unlink tags from queries","tags":["Tags"],"x-public-api":true}},"/api/v1/tag-groups":{"get":{"description":"Returns the list of tag groups of one taxonomy.","operationId":"TagGroupsV1Controller_list_v1","parameters":[{"name":"tagType","required":true,"in":"query","description":"Which tag taxonomy to list the groups of.","schema":{"$ref":"#/components/schemas/TagGroupTagType"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagGroupResponse"}}}}},"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"}}}}},"summary":"List tag groups","tags":["Tag Groups"],"x-public-api":true},"post":{"description":"Creates a folder for tags of one taxonomy.","operationId":"TagGroupsV1Controller_create_v1","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/CreateTagGroupDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagGroupResponse"}}}},"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"}}}}},"summary":"Create a tag group","tags":["Tag Groups"],"x-public-api":true}},"/api/v1/tag-groups/{id}":{"delete":{"description":"Deletes a tag group; returns no content on success. Member tags are never deleted — they become ungrouped.","operationId":"TagGroupsV1Controller_delete_v1","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the tag group to delete.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Delete a tag group","tags":["Tag Groups"],"x-public-api":true},"patch":{"description":"Renames or recolors a tag group; returns no content on success. The taxonomy is immutable.","operationId":"TagGroupsV1Controller_update_v1","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the tag group to update.","schema":{"format":"uuid","type":"string"}},{"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/UpdateTagGroupDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Update a tag group","tags":["Tag Groups"],"x-public-api":true}},"/api/v1/execution-tags/many":{"post":{"description":"Creates multiple execution tags from the supplied array.","operationId":"ExecutionTagsV1Controller_createMany_v1","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/CreateManyTagsJobExecutionNewDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagJobExecutionNewResponse"}}}}},"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"}}}}},"summary":"Create multiple execution tags","tags":["Execution Tags"],"x-public-api":true}},"/api/v1/execution-tags/bulk/group":{"post":{"description":"Files every execution tag in the selection (either explicit ids, or all execution tags matching a filter except the excluded ids) under the given tag group node, or ungroups them when groupId is null. Never triggers tag re-matching or re-embedding.","operationId":"ExecutionTagsV1Controller_bulkMoveToGroup_v1","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/BulkGroupExecutionTagsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkActionResponse"}}}},"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"}}}}},"summary":"Move a selection of execution tags to a group","tags":["Execution Tags"],"x-public-api":true}},"/api/v1/execution-tags/list":{"post":{"description":"Returns a paginated list of the project's execution tags matching the filters in the request body.","operationId":"ExecutionTagsV1Controller_list_v1","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"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/ListTagJobExecutionNewDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagingResponse"}],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/TagJobExecutionNewResponse"}},"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"}}}}},"summary":"List all execution tags","tags":["Execution Tags"],"x-public-api":true}},"/api/v1/execution-tags/{id}":{"get":{"description":"Retrieves a single execution tag by its id.","operationId":"ExecutionTagsV1Controller_getOne_v1","parameters":[{"name":"id","required":true,"in":"path","description":"UUID of the execution tag to retrieve.","schema":{"type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagJobExecutionNewResponse"}}}},"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"}}}}},"summary":"Get an execution tag","tags":["Execution Tags"],"x-public-api":true},"delete":{"description":"Deletes an execution tag; rejected if no matching tag exists in the project.","operationId":"ExecutionTagsV1Controller_remove_v1","parameters":[{"name":"id","required":true,"in":"path","description":"UUID of the execution tag to delete.","schema":{"type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Delete an execution tag","tags":["Execution Tags"],"x-public-api":true},"patch":{"description":"Updates an execution tag; rejected if no matching tag exists in the project. For an exact tag, a rename or a mode change recomputes all of its execution links, manual links included. For a semantic tag, new answers use the new definition at once and past answers change on the next history re-sync.","operationId":"ExecutionTagsV1Controller_update_v1","parameters":[{"name":"id","required":true,"in":"path","description":"UUID of the execution tag to update.","schema":{"type":"string"}},{"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/UpdateTagJobExecutionNewDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Update an execution tag","tags":["Execution Tags"],"x-public-api":true}},"/api/v1/execution-tags/link/many":{"post":{"description":"Links the given execution tags to the given job executions; existing links are ignored, and the call fails if any tag or job execution is not in the project. Renaming a tag or changing its matching mode recomputes all of the tag's execution links, manual links included.","operationId":"ExecutionTagsV1Controller_linkManyToJobExecutions_v1","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/LinkManyTagsJobExecutionNewDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Link execution tags to job executions","tags":["Execution Tags"],"x-public-api":true}},"/api/v1/execution-tags/unlink/many":{"post":{"description":"Removes the links between the given execution tags and job executions; fails if any tag or job execution is not in the project. Renaming a tag or changing its matching mode recomputes all of the tag's execution links, manual changes included.","operationId":"ExecutionTagsV1Controller_unlinkManyFromJobExecutions_v1","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/UnlinkManyTagsJobExecutionNewDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Unlink execution tags from job executions","tags":["Execution Tags"],"x-public-api":true}},"/api/analytics/custom-metrics":{"get":{"description":"Lists the custom metrics granted by the organisation's plan, ordered for dashboard display.","operationId":"CustomMetricsController_list","parameters":[{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListCustomMetricsResponse"}}}},"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"}}}}},"summary":"List custom metrics the current organisation has access to","tags":["Analytics - Custom Metrics"],"x-public-api":true}},"/api/analytics/custom-metrics/table":{"post":{"description":"Runs the requested table-shaped custom metric for the project and returns its results; the supplied filter is validated and the metric must be granted by your plan.","operationId":"CustomMetricsController_table","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/DispatchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TableEnvelope"}}}},"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"}}}}},"summary":"Get the values of a table-shaped custom metric","tags":["Analytics - Custom Metrics"],"x-public-api":true}},"/api/analytics/custom-metrics/timeseries":{"post":{"description":"Runs the requested timeseries-shaped custom metric for the project and returns its results; the supplied filter is validated and the metric must be granted by your plan.","operationId":"CustomMetricsController_timeseries","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/DispatchRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeseriesEnvelope"}}}},"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"}}}}},"summary":"Get the values of a timeseries-shaped custom metric","tags":["Analytics - Custom Metrics"],"x-public-api":true}},"/api/projects/theme-analysis/status":{"get":{"description":"Read-only progress snapshot: whether an analysis is running (extraction/clustering in flight), pending (completed prompt runs queued for the next poll), or idle (up to date), plus the underlying counts.","operationId":"ThemeAnalysisController_getStatus","parameters":[{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThemeAnalysisStatusResponse"}}}},"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"}}}}},"summary":"Theme-analysis pipeline status for the project","tags":["Theme Analysis"],"x-public-api":true}},"/api/projects/theme-analysis/run-pending":{"post":{"description":"Immediately enqueues the project terminal jobs not yet handed off for theme analysis (the same set the poller would pick up within ~1 min). Requires the project toggle to be on. Pass force=true to also re-run already-processed jobs.","operationId":"ThemeAnalysisController_runPending","parameters":[{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunPendingThemeAnalysisDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunPendingThemeAnalysisResponse"}}}},"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"}}}}},"summary":"Run theme analysis on the project's pending completed jobs","tags":["Theme Analysis"],"x-public-api":true}},"/api/entity-types":{"get":{"description":"Every type with its labels, and whether the organisation can create a project of it now.","operationId":"EntityTypesController_list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EntityTypeResponse"}}}}},"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"}}}}},"summary":"List the entity types a project can track","tags":["Entity Types"],"x-public-api":true}},"/api/entity-groups":{"post":{"description":"Creates a new entity container and returns it. By default a top-level group; pass kind \"division\" (optionally with a parentId) to create a division.","operationId":"EntityGroupsController_create","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/CreateEntityGroupDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroupResponse"}}}},"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"}}}}},"summary":"Create a new entity group","tags":["Entity Groups"],"x-public-api":true}},"/api/entity-groups/{id}":{"get":{"description":"Returns a single entity group by its ID.","operationId":"EntityGroupsController_findOne","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the entity group to retrieve.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGroupResponse"}}}},"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"}}}}},"summary":"Get entity group by ID","tags":["Entity Groups"],"x-public-api":true},"delete":{"description":"Permanently deletes an entity group; returns no content on success.","operationId":"EntityGroupsController_delete","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the entity group to delete.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Delete an entity group","tags":["Entity Groups"],"x-public-api":true},"patch":{"description":"Applies a partial update to an entity group; returns no content on success.","operationId":"EntityGroupsController_update","parameters":[{"name":"id","required":true,"in":"path","description":"The UUID of the entity group to update.","schema":{"format":"uuid","type":"string"}},{"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/UpdateEntityGroupDto"}}}},"responses":{"204":{"description":""},"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"}}}}},"summary":"Update an entity group","tags":["Entity Groups"],"x-public-api":true}},"/api/entity-groups/list":{"post":{"description":"Returns a paginated list of entity groups matching the supplied filters.","operationId":"EntityGroupsController_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/ListEntityGroupsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagingResponse"}],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/EntityGroupResponse"}},"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"}}}}},"summary":"List entity groups","tags":["Entity Groups"],"x-public-api":true}},"/api/v1/entity-groups/{id}/entities":{"put":{"description":"Adds the given entities to the entity group; entities already in the group are unaffected.","operationId":"EntityGroupsV1Controller_assignEntities_v1","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier (UUID) of the entity group to add entities to.","schema":{"format":"uuid","type":"string"}},{"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/AssignEntitiesToGroupDto"}}}},"responses":{"204":{"description":"Entities were added to the group."},"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"}}}}},"summary":"Add entities to a group","tags":["Entity Groups"],"x-public-api":true},"delete":{"description":"Removes the given entities from the entity group; entities not currently in the group are unaffected.","operationId":"EntityGroupsV1Controller_removeEntities_v1","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier (UUID) of the entity group to remove entities from.","schema":{"format":"uuid","type":"string"}},{"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/AssignEntitiesToGroupDto"}}}},"responses":{"204":{"description":"Entities were removed from the group."},"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"}}}}},"summary":"Remove entities from a group","tags":["Entity Groups"],"x-public-api":true}},"/api/source-categories/list":{"post":{"description":"Returns the global source-category catalog (the taxonomy leaves) for use as manual override options, ordered by label.","operationId":"SourceCategoriesController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":250,"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/ListSourceCategoriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagingResponse"}],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SourceCategoryResponse"}},"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"}}}}},"summary":"List source categories","tags":["Source Categories"],"x-public-api":true}},"/api/v1/analytics/models/timeseries":{"post":{"description":"Returns a per-AI-model time series of the chosen metric (citation, share of voice, position, or visibility) bucketed by `bucketSize`; for position the value is an average rank (lower is better), for the others a percentage (higher is better).","operationId":"ModelsV1Controller_getTimeseries_v1","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/ModelsTimeseriesV1Dto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ModelTimeseriesV1Point"}}}}},"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"}}}}},"summary":"Per-AI-model metric timeseries","tags":["Analytics - Models"],"x-public-api":true}},"/api/v1/analytics/sources/domains":{"post":{"description":"Returns the project's cited source domains with citation and brand-reach metrics over the selected date range; pass `limit` for a top-N view.","operationId":"SourcesV1Controller_getDomains_v1","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/SourceAllDomainsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceAllDomainsResponse"}}}},"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"}}}}},"summary":"Source domains with citation & brand-reach metrics","tags":["Analytics - Sources"],"x-public-api":true}},"/api/v1/analytics/sources/breakdown":{"post":{"description":"Aggregates the project's in-scope citations along one axis selected by the required `dimension`. Returns each bucket's citation count and share.","operationId":"SourcesV1Controller_getBreakdown_v1","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/SourcesBreakdownDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcesBreakdownResponse"}}}},"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"}}}}},"summary":"Citation breakdown by source type, group, relationship or controllability","tags":["Analytics - Sources"],"x-public-api":true}},"/api/v1/analytics/sources/domains/timeseries":{"post":{"description":"Returns a bucketed timeseries of citation share and rate for the top 5 source domains over the selected date range.","operationId":"SourcesV1Controller_getTimeseries_v1","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/SourceTimeseriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceTimeseriesResponse"}}}},"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"}}}}},"summary":"Timeseries of top source domains by citation share","tags":["Analytics - Sources"],"x-public-api":true}},"/api/v1/analytics/sources/domains/{sourceDomainId}/entities":{"post":{"description":"Returns the entities found on pages cited from the given domain with their citation and reach metrics; the path domain id overrides any body value, and an unknown domain returns an empty list.","operationId":"SourcesV1Controller_getDomainEntities_v1","parameters":[{"name":"sourceDomainId","required":true,"in":"path","description":"Identifier of the source domain whose cited entities are returned. Overrides any value in the request body.","schema":{"example":"d1f8c3a2-9b4e-4c7a-8f21-6e0a5b2c9d10","type":"string"}},{"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/SourceDomainEntitiesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDomainEntitiesResponse"}}}},"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"}}}}},"summary":"Entities found on a specific domain with true reach","tags":["Analytics - Sources"],"x-public-api":true}},"/api/v1/analytics/sources/domains/{sourceDomainId}/urls":{"post":{"description":"Returns a paginated list of the individual URLs cited from the given domain with their citation metrics; the path domain id overrides any body value, and an unknown domain returns an empty page.","operationId":"SourcesV1Controller_getDomainUrls_v1","parameters":[{"name":"sourceDomainId","required":true,"in":"path","description":"Identifier of the source domain whose cited URLs are returned. Overrides any value in the request body.","schema":{"example":"d1f8c3a2-9b4e-4c7a-8f21-6e0a5b2c9d10","type":"string"}},{"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/SourceDomainUrlsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDomainUrlsResponse"}}}},"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"}}}}},"summary":"Per-URL drill-down for a specific domain","tags":["Analytics - Sources"],"x-public-api":true}},"/api/v1/analytics/sources/domains/{sourceDomainId}/urls/queries":{"post":{"description":"Returns the queries that cited a specific URL on the given domain, ordered by citation count; the path domain id overrides any body value, and an unknown domain or URL returns an empty list.","operationId":"SourcesV1Controller_getUrlQueries_v1","parameters":[{"name":"sourceDomainId","required":true,"in":"path","description":"Identifier of the source domain that hosts the target URL. Overrides any value in the request body.","schema":{"example":"d1f8c3a2-9b4e-4c7a-8f21-6e0a5b2c9d10","type":"string"}},{"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/SourceUrlQueriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceUrlQueriesResponse"}}}},"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"}}}}},"summary":"Queries that cited a specific URL on a domain","tags":["Analytics - Sources"],"x-public-api":true}},"/api/v1/analytics/shopping/products":{"post":{"description":"Returns a paginated, sortable list of products mentioned in shopping AI responses for the project, with visibility, pricing and rating metrics and their top merchants.","operationId":"ShoppingV1Controller_getProducts_v1","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/ShoppingAllProductsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShoppingAllProductsResponse"}}}},"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"}}}}},"summary":"List products with shopping metrics","tags":["Analytics - Shopping"],"x-public-api":true}},"/api/v1/analytics/shopping/brands":{"post":{"description":"Returns a paginated, sortable list of brands appearing in shopping AI responses for the project, with product count, visibility, pricing metrics, top merchants and share of voice.","operationId":"ShoppingV1Controller_getBrands_v1","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/ShoppingAllBrandsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShoppingAllBrandsResponse"}}}},"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"}}}}},"summary":"List brands with shopping metrics","tags":["Analytics - Shopping"],"x-public-api":true}},"/api/v1/analytics/shopping/merchants":{"post":{"description":"Returns a paginated, sortable list of merchants cited in shopping AI responses for the project, with citation and offer-quality metrics across all merchants, plus reach metrics scoped to the requested brands.","operationId":"ShoppingV1Controller_getMerchants_v1","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/ShoppingAllMerchantsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShoppingAllMerchantsResponse"}}}},"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"}}}}},"summary":"List merchants with citation metrics","tags":["Analytics - Shopping"],"x-public-api":true}},"/api/v1/analytics/fan-outs":{"post":{"description":"Returns the most common fan-outs (search queries the AI ran) ranked by occurrence count.","operationId":"FanOutsV1Controller_getTop_v1","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/FanOutsFilterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FanOutsTopResponse"}}}},"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"}}}}},"summary":"Top fan-outs by occurrence","tags":["Analytics - Fan Outs"],"x-public-api":true}},"/api/v1/analytics/fan-outs/overview":{"post":{"description":"Returns summary fan-out statistics for the project, including total and unique fan-outs and the average number per AI response with fan-outs.","operationId":"FanOutsV1Controller_getOverview_v1","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/FanOutsFilterDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FanOutsOverviewResponse"}}}},"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"}}}}},"summary":"Fan-outs overview stats","tags":["Analytics - Fan Outs"],"x-public-api":true}},"/api/v1/analytics/fan-outs/queries":{"post":{"description":"Per-query fan-out statistics across the project.","operationId":"FanOutsV1Controller_getByQuery_v1","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/FanOutsByQueryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FanOutsByQueryResponse"}}}},"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"}}}}},"summary":"Fan-out stats per query","tags":["Analytics - Fan Outs"],"x-public-api":true}},"/api/v1/analytics/fan-outs/queries/{queryId}/fan-outs":{"post":{"description":"Returns the individual fan-out texts for a single query; the path `queryId` overrides any value in the body.","operationId":"FanOutsV1Controller_getForQuery_v1","parameters":[{"name":"queryId","required":true,"in":"path","description":"UUID of the query to retrieve individual fan-out texts for.","schema":{"example":"3f1a2b4c-5d6e-7f80-9a1b-2c3d4e5f6071","type":"string"}},{"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/FanOutsForQueryDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FanOutsForQueryResponse"}}}},"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"}}}}},"summary":"Fan-outs for a specific query","tags":["Analytics - Fan Outs"],"x-public-api":true}},"/api/v1/analytics/social/youtube/videos":{"post":{"description":"Returns a paginated list of YouTube videos cited by AI responses in the selected scope, with per-video citation metrics; pass `channelId` to drill down to a single channel.","operationId":"SocialV1Controller_listYoutubeVideos_v1","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/YoutubeVideosDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeVideosResponse"}}}},"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"}}}}},"summary":"List YouTube videos cited in scope","tags":["Analytics - Social"],"x-public-api":true}},"/api/v1/analytics/social/youtube/channels":{"post":{"description":"Returns a paginated list of YouTube channels cited by AI responses in the selected scope, with citation metrics aggregated across each channel's cited videos.","operationId":"SocialV1Controller_listYoutubeChannels_v1","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/YoutubeChannelsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeChannelsResponse"}}}},"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"}}}}},"summary":"List YouTube channels cited in scope","tags":["Analytics - Social"],"x-public-api":true}},"/api/v1/analytics/social/youtube/countries":{"post":{"description":"Returns a paginated breakdown of YouTube citation performance by each cited channel's country; channels with no country are grouped together.","operationId":"SocialV1Controller_listYoutubeCountries_v1","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/YoutubeCountriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeCountriesResponse"}}}},"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"}}}}},"summary":"List YouTube performance by channel country","tags":["Analytics - Social"],"x-public-api":true}},"/api/v1/analytics/social/youtube/kpis":{"post":{"description":"Returns a compact KPI summary of YouTube social activity in the selected scope.","operationId":"SocialV1Controller_getYoutubeKpis_v1","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/YoutubeKpisDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeKpisResponse"}}}},"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"}}}}},"summary":"KPI summary for YouTube social in scope","tags":["Analytics - Social"],"x-public-api":true}},"/api/v1/analytics/social/youtube/channels/timeseries":{"post":{"description":"Returns a day/week/month timeseries of the top 5 YouTube channels by citation share, with every channel present in each bucket (0 when absent).","operationId":"SocialV1Controller_getYoutubeChannelsTimeseries_v1","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/YoutubeChannelsTimeseriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeChannelsTimeseriesResponse"}}}},"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"}}}}},"summary":"Timeseries of top 5 YouTube channels by citation share","tags":["Analytics - Social"],"x-public-api":true}},"/api/v1/analytics/social/youtube/videos/{videoId}/queries":{"post":{"description":"Returns the queries whose AI responses cited the given YouTube video in the selected scope; the path `videoId` overrides any value in the body.","operationId":"SocialV1Controller_getYoutubeVideoQueries_v1","parameters":[{"name":"videoId","required":true,"in":"path","description":"YouTube video identifier whose citing queries are returned (the YouTube video ID, not an internal identifier).","schema":{"example":"dQw4w9WgXcQ","type":"string"}},{"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/YoutubeVideoQueriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YoutubeVideoQueriesResponse"}}}},"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"}}}}},"summary":"Queries that cited a specific YouTube video","tags":["Analytics - Social"],"x-public-api":true}},"/api/v1/analytics/queries/stats":{"post":{"description":"Returns per-query statistics for the project; to fetch a single query, pass `queryIds: [id]` and read `queries[0]`.","operationId":"QueriesStatsV1Controller_getStats_v1","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/QueriesStatsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueriesStatsResponse"}}}},"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"}}}}},"summary":"Per-query statistics","tags":["Analytics - Queries"],"x-public-api":true}},"/api/v1/analytics/tags/entities":{"post":{"description":"Returns the top `limit` entities per tag (default 20, max 100), ordered by visibility unless `sort` says otherwise, with the size of the full list (`entityCount`). `focus` returns the `focusKeys` entities and the primary entity with their rank, even outside the top `limit`.","operationId":"TagsAnalyticsV1Controller_getEntities_v1","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/TagEntitiesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagEntitiesResponse"}}}},"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"}}}}},"summary":"Entities detected for one or more tags","tags":["Analytics - Tags"],"x-public-api":true}},"/api/v1/analytics/tags/presence":{"post":{"description":"Returns every execution tag for the project with the percentage of AI responses (matching the filters) that carry that tag.","operationId":"TagsAnalyticsV1Controller_getPresence_v1","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/TagsPresenceDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TagsPresencePoint"}}}}},"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"}}}}},"summary":"Execution-tag response presence","tags":["Analytics - Tags"],"x-public-api":true}},"/api/v1/analytics/visibility/timeseries":{"post":{"description":"Returns a visibility, average-position, mention-count and sentiment timeseries for each tracked entity over the selected date range.","operationId":"VisibilityV1Controller_getTimeseries_v1","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/VisibilityTimeseriesDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EntitiesTimeseriesPoint"}}}}},"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"}}}}},"summary":"Per-entity visibility/position/sentiment timeseries","tags":["Analytics - Visibility"],"x-public-api":true}},"/api/v1/source-topics/preview":{"post":{"description":"Runs the exact same source selection as the extraction trigger — the top sources (by citation count) matching the standard analytics filters — but enqueues nothing. Returns the selected sources grouped by domain so the frontend can let the user assess the scope before triggering.","operationId":"SourceTopicsV1Controller_previewTopics_v1","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/SourceTopicsExtractDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceTopicsPreviewResponse"}}}},"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"}}}}},"summary":"Preview the sources a topic extraction would hit","tags":["Source Topics"],"x-public-api":true}},"/api/v1/source-topics/extract":{"post":{"description":"Selects the top 1000 source pages (deduped per url + month, ranked by citation count) matching the standard analytics filters (date range, countries, languages, models, queries, tags) and enqueues their cached page metadata (title + description) for vectorization into the source-topics vector store. Use /source-topics/preview to inspect the selected set first. Returns the id of the created run and the number of enqueued jobs. Every trigger creates a NEW run; extracts are serialized per project — a 409 is returned while another extraction run is in flight. Sources whose metadata was not cached at scrape time are skipped by the worker.","operationId":"SourceTopicsV1Controller_extractTopics_v1","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/SourceTopicsExtractDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceTopicsExtractResponse"}}}},"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"}}}}},"summary":"Trigger topic extraction for the sources in scope","tags":["Source Topics"],"x-public-api":true}},"/api/v1/source-topics/runs":{"get":{"description":"Returns the projects topic-extraction runs, most recent first, with their status and progress counters. Poll this (or the per-run endpoint) to drive a loading indicator.","operationId":"SourceTopicsV1Controller_listTopicRuns_v1","parameters":[{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceTopicRunsListResponse"}}}},"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"}}}}},"summary":"List topic-extraction runs for the project","tags":["Source Topics"],"x-public-api":true}},"/api/v1/source-topics/runs/{runId}":{"get":{"description":"Returns the status and progress counters of one topic-extraction run. Use processed / totalSources for a progress bar.","operationId":"SourceTopicsV1Controller_getTopicRun_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"UUID of the run to retrieve.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceTopicRunResponse"}}}},"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"}}}}},"summary":"Get a single topic-extraction run","tags":["Source Topics"],"x-public-api":true},"delete":{"description":"Removes a run from the project run history (soft delete). The run no longer appears in the list or single-run endpoints. Any vectors it produced remain in the store.","operationId":"SourceTopicsV1Controller_deleteTopicRun_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"UUID of the run to delete.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":""},"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"}}}}},"summary":"Delete a topic-extraction run","tags":["Source Topics"],"x-public-api":true}},"/api/v1/source-topics/runs/{runId}/topics":{"get":{"description":"Returns the topics (density clusters of the embedded source metadata, named by an LLM) for a run, biggest first. Topics are produced automatically once embedding completes — poll the run until its `topicsStatus` is `ready`, then read them here. Empty while clustering is pending/running or when no dense topics were found.","operationId":"SourceTopicsV1Controller_listTopicRunTopics_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"UUID of the run whose topics to retrieve.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceTopicTopicsListResponse"}}}},"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"}}}}},"summary":"List the topics extracted for a run","tags":["Source Topics"],"x-public-api":true}},"/api/v1/source-topics/runs/{runId}/content-gap":{"get":{"description":"Crosses the run’s topics with the source classification: per topic, whether the project’s owned entity has content on it (present = covered, absent = content gap), whether competitors do, the topic’s citation share, and its \"ownable\" (controllability) source mix. Ordered by citation share descending; use isContentGap to surface or filter the gaps among the top-cited topics. Presence needs the project’s relationship overlay populated (map entity domains + recompute); otherwise every topic reads as a gap. Empty while clustering is pending — poll the run until `topicsStatus` is `ready`.","operationId":"SourceTopicsV1Controller_getContentGap_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"UUID of the run whose content gap to retrieve.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentGapResponse"}}}},"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"}}}}},"summary":"Content gap for a run (all topics)","tags":["Source Topics"],"x-public-api":true}},"/api/v1/source-topics/runs/{runId}/content-gap/topics/{topicId}":{"get":{"description":"Lists every source (cited page snapshot) grouped in the topic, each with whether it’s the project’s own content (“is my brand present”), its relationship + controllability + source-type category, the queries it was cited from, and its citation count — sorted most-cited first.","operationId":"SourceTopicsV1Controller_getContentGapTopicDetail_v1","parameters":[{"name":"runId","required":true,"in":"path","description":"UUID of the run the topic belongs to.","schema":{"format":"uuid","type":"string"}},{"name":"topicId","required":true,"in":"path","description":"UUID of the topic (cluster) to detail.","schema":{"format":"uuid","type":"string"}},{"name":"x-project-id","in":"header","description":"Project ID to specify the project context","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentGapTopicDetailResponse"}}}},"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"}}}}},"summary":"Content-gap detail for one topic (its sources)","tags":["Source Topics"],"x-public-api":true}},"/api/v1/reference/provider-restrictions":{"get":{"description":"Returns the list of provider/model entries with the countries each one is allowed to be used in; this is global reference data shared across all projects.","operationId":"ReferenceV1Controller_getProviderRestrictions_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProviderRestrictionsMapResponseDto"}}}}},"401":{"description":"The request is missing a valid API key."}},"summary":"Provider/model restrictions (allowed countries)","tags":["Reference"],"x-public-api":true}},"/api/v1/reference/locales":{"get":{"description":"Returns the allowlist of countries and languages that queries may target; this is global reference data shared across all projects.","operationId":"ReferenceV1Controller_getLocales_v1","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedLocalesResponse"}}}},"401":{"description":"The request is missing a valid API key."}},"summary":"Supported countries and languages allowlist","tags":["Reference"],"x-public-api":true}},"/api/shopping-products/items":{"post":{"description":"Returns a paginated list of the project's shopping products with their brand details and merchant URLs, filterable by brand, product, name search and external id.","operationId":"ShoppingProductsController_getItems","parameters":[{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"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/GetItemsDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PagingResponse"}],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ShoppingItemResponse"}},"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"}}}}},"summary":"List shopping products with merchant URLs","tags":["Shopping Products"],"x-public-api":true}}},"info":{"title":"MentionLab Public API v0.6.28-rc","description":"","version":"0.6.28-rc","contact":{}},"tags":[],"servers":[{"url":"https://api.mentionlab.io"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"AddAliasDto":{"type":"object","properties":{"alias":{"type":"string","description":"Alias text","example":"Samsung Electronics"}},"required":["alias"]},"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"]},"AssignEntitiesToGroupDto":{"type":"object","properties":{"entityIds":{"description":"Entity IDs to assign to this group","example":["550e8400-e29b-41d4-a716-446655440000","6ba7b810-9dad-11d1-80b4-00c04fd430c8"],"type":"array","items":{"type":"array"}}},"required":["entityIds"]},"BulkActionResponse":{"type":"object","properties":{"affected":{"type":"number","description":"Number of rows affected by the action.","example":42}},"required":["affected"]},"BulkGroupExecutionTagsDto":{"type":"object","properties":{"selection":{"description":"The response tags to move.","allOf":[{"$ref":"#/components/schemas/TagJobExecutionSelectionDto"}]},"groupId":{"type":"string","description":"Target execution-taxonomy tag group to file the tags under, or null to ungroup them.","format":"uuid","nullable":true,"example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"}},"required":["selection","groupId"]},"BulkGroupTagsDto":{"type":"object","properties":{"selection":{"description":"The tags to move.","allOf":[{"$ref":"#/components/schemas/TagSelectionDto"}]},"groupId":{"type":"string","description":"Target query-taxonomy tag group to file the tags under, or null to ungroup them.","format":"uuid","nullable":true,"example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"}},"required":["selection","groupId"]},"BulkUnmergeEntitiesDto":{"type":"object","properties":{"ids":{"description":"Merged-away entity ids to make independent again. Ids that are not merged are skipped.","example":["019daf29-0000-7000-8000-0000000000b1"],"type":"array","items":{"type":"string"}},"survivorIds":{"description":"Survivor ids. Everything currently merged into one of these is released. Combined with `ids` when both are given.","example":["019daf29-0000-7000-8000-0000000000a1"],"type":"array","items":{"type":"string"}}}},"BulkUnmergeEntitiesResponse":{"type":"object","properties":{"unmerged":{"type":"number","description":"Entities made independent again.","example":128},"ids":{"description":"The entities that were released.","example":["019daf29-0000-7000-8000-0000000000b1"],"type":"array","items":{"type":"string"}}},"required":["unmerged","ids"]},"BulkUpdateEntitiesDto":{"type":"object","properties":{"ids":{"description":"Entity IDs to update (must belong to the current project)","example":["f47ac10b-58cc-4372-a567-0e02b2c3d479","550e8400-e29b-41d4-a716-446655440000"],"type":"array","items":{"type":"string"}},"isOwned":{"type":"boolean","description":"Mark entities as owned by the project","example":true},"isCompetitor":{"type":"boolean","description":"Mark entities as competitors","example":false},"isBlacklisted":{"type":"boolean","description":"Mark entities as blacklisted (excludes from analysis but preserves history)","example":false}},"required":["ids"]},"ChatgptAdsAdvertiserShare":{"type":"object","properties":{"advertiser":{"type":"string","description":"Advertiser name as the provider labels the ad unit (who paid for the slot, often a retailer). Raw wire string, never entity-resolved.","example":"SCHEELS"},"adCount":{"type":"number","description":"This advertiser's ad cards (placements) in the filtered scope — a 5-card carousel weighs 5. Density signal; the share is unit-based.","example":12},"share":{"type":"number","description":"Share of ad units — \"when an ad shows, whose ad is it\": this advertiser's ad units (responseCount) over totalUnits. Formula: (responseCount / totalUnits) × 100. Sums to 100% across advertisers, up to per-row rounding.","example":40},"responseCount":{"type":"number","description":"AI responses in the filtered scope that rendered at least one of this advertiser's ad cards.","example":9},"adRate":{"type":"number","description":"This advertiser's ad rate — responses carrying at least one of its ad cards over ALL responses in scope. Formula: (responseCount / totalResponses) × 100.","example":4.5},"avgPosition":{"type":"number","description":"Average render position of this advertiser's ad cards (1 = first card of the unit), rounded to 1 decimal.","example":1.4}},"required":["advertiser","adCount","share","responseCount","adRate","avgPosition"]},"ChatgptAdsAdvertisersResponse":{"type":"object","properties":{"adRate":{"type":"number","description":"Percentage of AI responses that rendered at least one sponsored ad card, out of total responses in the filtered scope. Identical definition to the overview adsRate.","example":12.34},"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope.","example":1500},"totalAdResponses":{"type":"number","description":"AI responses in the filtered scope that rendered at least one ad card.","example":185},"totalAds":{"type":"number","description":"Total ad cards (placements) in the filtered scope — a 5-card carousel weighs 5.","example":320},"totalUnits":{"type":"number","description":"Total ad units summed over the advertiser groups — the denominator for each advertiser share. A unit carrying more than one advertiser counts once per advertiser.","example":95},"advertisers":{"description":"Per-advertiser ad share, sorted by share descending. Every placement carries an advertiser, so shares sum to 100%, up to per-row rounding.","type":"array","items":{"$ref":"#/components/schemas/ChatgptAdsAdvertiserShare"}}},"required":["adRate","totalResponses","totalAdResponses","totalAds","totalUnits","advertisers"]},"ChatgptAdsBrandShare":{"type":"object","properties":{"entityId":{"type":"string","description":"Canonical entity ID of the advertised brand. Merged-away entities are collapsed into their canonical entity.","example":"550e8400-e29b-41d4-a716-446655440000"},"entityName":{"type":"string","description":"Canonical entity display name.","example":"Garmin"},"adCount":{"type":"number","description":"This brand's ad cards (placements) in the filtered scope — a 5-card carousel weighs 5. Density signal; the share is unit-based.","example":12},"share":{"type":"number","description":"Share of ad units — \"when an ad shows, whose ad is it\": this brand's ad units (responseCount) over totalUnits. Formula: (responseCount / totalUnits) × 100. Sums to 100% across brands unless unattributed units are in scope (they count in totalUnits but have no brand row).","example":40},"responseCount":{"type":"number","description":"AI responses in the filtered scope that rendered at least one of this brand's ad cards.","example":9},"adRate":{"type":"number","description":"This brand's ad rate — responses carrying at least one of its ad cards over ALL responses in scope (the mention-rate analogue for ads). Formula: (responseCount / totalResponses) × 100.","example":4.5},"avgPosition":{"type":"number","description":"Average render position of this brand's ad cards (1 = first card of the unit), rounded to 1 decimal — who consistently buys the top slot.","example":1.4}},"required":["entityId","entityName","adCount","share","responseCount","adRate","avgPosition"]},"ChatgptAdsBrandsResponse":{"type":"object","properties":{"adRate":{"type":"number","description":"Percentage of AI responses that rendered at least one sponsored ad card, out of total responses in the filtered scope. Formula: (totalAdResponses / totalResponses) × 100. 0 when there are no responses. Identical definition to the overview adsRate.","example":12.34},"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope.","example":1500},"totalAdResponses":{"type":"number","description":"AI responses in the filtered scope that rendered at least one ad card.","example":185},"totalAds":{"type":"number","description":"Total ad cards (placements) in the filtered scope — a 5-card carousel weighs 5.","example":320},"totalUnits":{"type":"number","description":"Total ad units summed over ALL groups including the unattributed one — the denominator for each brand share. A unit carrying more than one brand counts once per brand.","example":95},"brands":{"description":"Per-brand ad share, one row per canonical entity, sorted by share descending.","type":"array","items":{"$ref":"#/components/schemas/ChatgptAdsBrandShare"}}},"required":["adRate","totalResponses","totalAdResponses","totalAds","totalUnits","brands"]},"ChatgptAdsFilterDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"formats":{"description":"Filter ad placements by card format (provider-defined open set, e.g. 'product_card_v2', 'image_card_v2'). Scopes totalAds and the brand rows only; adRate and the response totals remain format-agnostic.","example":["image_card_v2"],"type":"array","items":{"type":"string"}}}},"ChatgptAdsFormatShare":{"type":"object","properties":{"format":{"type":"string","description":"Ad card format, as the provider names it (open set, e.g. 'product_card_v2', 'image_card_v2'). Raw string, not normalized.","example":"product_card_v2"},"adCount":{"type":"number","description":"Ad cards (placements) with this format in the filtered scope — a 5-card carousel weighs 5. Secondary density signal; the share is unit-based.","example":80},"unitCount":{"type":"number","description":"Ad units (distinct AI responses) that rendered at least one card of this format — a 5-card carousel weighs 1.","example":16},"share":{"type":"number","description":"Share of ad units — \"when an ad shows, how often is it this format\". Formula: (unitCount / totalUnits) × 100. Sums to 100% across formats, up to per-row rounding.","example":16.8}},"required":["format","adCount","unitCount","share"]},"ChatgptAdsFormatsResponse":{"type":"object","properties":{"totalAds":{"type":"number","description":"Total ad cards (placements) in the filtered scope — a 5-card carousel weighs 5.","example":159},"totalUnits":{"type":"number","description":"Total ad units summed over the format groups — the denominator for each format share. A unit carrying more than one format counts once per format.","example":95},"formats":{"description":"Ad-format mix, unit-weighted, sorted by share descending. Honors the formats filter (a filtered breakdown sums to 100% within the selected formats, up to per-row rounding).","type":"array","items":{"$ref":"#/components/schemas/ChatgptAdsFormatShare"}}},"required":["totalAds","totalUnits","formats"]},"ContentGapControllabilityMix":{"type":"object","properties":{"owned":{"type":"number","description":"Sources on an owned domain (relationship = owned).","example":2},"earnable":{"type":"number","description":"Sources we can realistically earn/produce content on (PR, outreach, reviews, UGC, partnerships…).","example":7},"hard":{"type":"number","description":"Low-control sources (encyclopedic, academic, government, others’ corporate sites).","example":4},"unknown":{"type":"number","description":"Unclassified sources (source type = other).","example":1}},"required":["owned","earnable","hard","unknown"]},"ContentGapResponse":{"type":"object","properties":{"runId":{"type":"string","description":"The run whose content gap this describes.","example":"019dd32e-b19e-7956-88f6-4b9a877f3697"},"topicsStatus":{"description":"Clustering status of the run. Topics only exist once this is `ready`; poll until then.","example":"ready","allOf":[{"$ref":"#/components/schemas/SourceTopicTopicsStatus"}]},"totalCitations":{"type":"number","description":"Sum of citationCount across all topics — the denominator for citationShare.","example":691},"analyzedSources":{"type":"number","description":"Number of sources the run analyzed for topics. The difference vs the sum of topic sizes is sources that did not group into any topic.","example":96},"ownedDomainsMapped":{"type":"boolean","description":"Whether the project has any source domains mapped as `owned`. When false, no topic can be marked covered — every row reads as a content gap regardless of the data. Prompt the user to map their brand’s domains.","example":true},"competitorDomainsMapped":{"type":"boolean","description":"Whether the project has any source domains mapped as `competitor`. When false, competitorPresent is always false.","example":true},"topics":{"description":"Topics ordered by citationShare descending. Use isContentGap to surface/filter the gaps among the top-cited topics.","type":"array","items":{"$ref":"#/components/schemas/ContentGapTopicResponse"}}},"required":["runId","topicsStatus","totalCitations","analyzedSources","ownedDomainsMapped","competitorDomainsMapped","topics"]},"ContentGapSourceQuery":{"type":"object","properties":{"queryId":{"type":"string","description":"Query UUID.","example":"019dd32e-b19e-7956-88f6-4b9a877f3697"},"query":{"type":"string","description":"Query text.","example":"best ev charging networks 2026"}},"required":["queryId","query"]},"ContentGapSourceResponse":{"type":"object","properties":{"url":{"type":"string","description":"Cited page URL.","example":"https://example.com/ev/charging-guide"},"domain":{"type":"string","description":"Root domain of the source.","example":"example.com"},"sourceDomainId":{"type":"string","description":"Source domain UUID.","example":"019dd32e-b19e-7956-88f6-4b9a877f3697"},"month":{"type":"string","description":"Month bucket (YYYY-MM) of the source snapshot.","example":"2026-06"},"relationship":{"type":"string","description":"Relationship of the source’s domain to the project: owned | competitor | partner_affiliate | independent.","example":"independent"},"ownedPresent":{"type":"boolean","description":"Whether this source is the project’s own content (relationship = owned) — \"is my brand present on this source\".","example":false},"controllability":{"type":"string","description":"Controllability of the source: owned | earnable | hard | unknown (how realistically we can produce/earn content there).","example":"earnable"},"categorySlug":{"type":"string","description":"Resolved source-type category slug (project override → global → other).","example":"news_media"},"categoryLabel":{"type":"string","description":"Human-readable label for categorySlug.","example":"News & Press"},"citationCount":{"type":"number","description":"Citations (distinct AI responses) of this source within the run’s scope.","example":23},"queries":{"description":"Queries this source was cited from.","type":"array","items":{"$ref":"#/components/schemas/ContentGapSourceQuery"}}},"required":["url","domain","sourceDomainId","month","relationship","ownedPresent","controllability","categorySlug","categoryLabel","citationCount","queries"]},"ContentGapTopicDetailResponse":{"type":"object","properties":{"id":{"type":"string","description":"Topic (cluster) UUID.","example":"019dd32e-b19e-7956-88f6-4b9a877f3697"},"label":{"type":"string","description":"LLM-assigned topic label.","example":"Electric vehicle charging"},"keywords":{"description":"Keywords summarizing the topic.","example":["ev charging","charging network"],"type":"array","items":{"type":"string"}},"size":{"type":"number","description":"Number of source snapshots grouped in this topic.","example":14},"ownedPresent":{"type":"boolean","description":"Whether the project’s owned entity has content on this topic.","example":false},"competitorPresent":{"type":"boolean","description":"Whether a competitor has content on this topic.","example":true},"isContentGap":{"type":"boolean","description":"Content-gap flag (owned entity absent).","example":true},"citationCount":{"type":"number","description":"Total citations across the topic’s sources within the run’s scope.","example":128},"sources":{"description":"The topic’s sources, most-cited first.","type":"array","items":{"$ref":"#/components/schemas/ContentGapSourceResponse"}}},"required":["id","label","keywords","size","ownedPresent","competitorPresent","isContentGap","citationCount","sources"]},"ContentGapTopicResponse":{"type":"object","properties":{"id":{"type":"string","description":"Topic (cluster) UUID.","example":"019dd32e-b19e-7956-88f6-4b9a877f3697"},"rank":{"type":"number","description":"1-based priority rank within the run (1 = highest citation weight at analysis time).","example":1},"label":{"type":"string","description":"LLM-assigned topic label.","example":"Electric vehicle charging"},"keywords":{"description":"Keywords summarizing the topic.","example":["ev charging","charging network","fast charger"],"type":"array","items":{"type":"string"}},"size":{"type":"number","description":"Number of source snapshots grouped in this topic.","example":14},"ownedPresent":{"type":"boolean","description":"Whether the project’s owned entity has content on this topic — i.e. at least one cited source in the topic sits on an owned domain. Requires the project’s relationship overlay to be populated (map entity domains + recompute); otherwise every topic reads as a gap.","example":false},"competitorPresent":{"type":"boolean","description":"Whether at least one cited source in the topic sits on a competitor domain.","example":true},"isContentGap":{"type":"boolean","description":"Content-gap flag — true when the owned entity is NOT present (nothing of ours covers this topic).","example":true},"citationCount":{"type":"number","description":"Total citations (distinct AI responses) across the topic’s source snapshots, within the run’s filter scope.","example":128},"citationShare":{"type":"number","description":"This topic’s share of the run’s total topic citations, as a percentage. Priority signal: high share + isContentGap = write here first.","example":18.5},"controllability":{"description":"Source-controllability mix — how \"ownable\" the topic’s sources are.","allOf":[{"$ref":"#/components/schemas/ContentGapControllabilityMix"}]}},"required":["id","rank","label","keywords","size","ownedPresent","competitorPresent","isContentGap","citationCount","citationShare","controllability"]},"CreateEntityDto":{"type":"object","properties":{"name":{"type":"string","description":"Entity name","example":"Samsung"},"type":{"type":"string","description":"Entity type","enum":["brand","person","company","other"],"default":"brand"},"level":{"type":"string","nullable":true,"description":"Tier inside the project's entity type, one of its levelVocab (GET /entity-types); null clears it","example":"city"},"isOwned":{"type":"boolean","description":"Is this entity owned by the project","example":true},"isPrimary":{"type":"boolean","description":"Is this the primary entity","example":false},"isCompetitor":{"type":"boolean","description":"Is this a competitor entity","example":false},"isBlacklisted":{"type":"boolean","description":"Is this entity blacklisted","example":false},"groupId":{"type":"string","description":"Entity group ID","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["name"]},"CreateEntityGroupDto":{"type":"object","properties":{"name":{"type":"string","description":"Group name","example":"Premium Brands"},"kind":{"type":"string","description":"What this container is. \"group\" is a top-level group; \"division\" can sit under a group or stand alone. Immutable after creation. Defaults to \"group\".","enum":["group","division"]},"parentId":{"type":"string","description":"Parent group for a division. Only divisions can have a parent, and the parent must be a group. Omit to create a top-level group or a standalone division.","format":"uuid","example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"}},"required":["name"]},"CreateFromProjectQueriesDto":{"type":"object","properties":{"aiModels":{"type":"array","description":"List of AI model identifiers to use for analysis","example":["scp-ml-chatgpt","claude-haiku-latest","gemini-2.5-flash"],"items":{"type":"string","enum":["claude-haiku-latest","gemini-flash-latest","sonar-latest","deepseek-pro-latest","mistral-large-latest","muse-spark-latest","gpt-4.1-mini","gpt-5-mini","gpt-5-chat-latest","gpt-5.1-chat-latest","gpt-5.2-chat-latest","gpt-5.3-chat-latest","claude-haiku-4-5","claude-haiku-5-5","gemini-2.5-flash","gemini-3.6-flash","gemini-3-flash-preview","gemini-3.5-flash-lite","gemini-3.1-flash-lite","gemini-2.5-flash-lite","sonar","deepseek-v3.2-maas","deepseek-v4-pro","mistral-large-3","muse-spark-1.3-contributor","ai-overview","ai-mode","scp-ml-chatgpt","scp-ml-gemini","scp-s-perplexity","scp-s-copilot"]}},"executionCount":{"type":"number","description":"The number of executions (runs) per job item","example":3,"minimum":1},"force":{"type":"boolean","description":"Bypass the duplicate-launch guard, which refuses a second launch within 10 minutes of the previous one for this project. Set to true only after the user has confirmed they intend to launch again.","example":false}},"required":["aiModels","executionCount"]},"CreateManyQueriesDto":{"type":"object","properties":{"queries":{"description":"List of queries to create in a single batch. Must contain at least one query, and each item is validated against the CreateQueryDto schema.","example":[{"query":"machine learning trends","language":"en","country":"US","type":"informative"}],"type":"array","items":{"$ref":"#/components/schemas/CreateQueryDto"}}},"required":["queries"]},"CreateManyTagsDto":{"type":"object","properties":{"tags":{"description":"List of tags to create in a single batch operation. Must contain at least one tag, and each entry is validated against the CreateTagDto schema.","example":[{"name":"Marketing","color":"#3B82F6"},{"name":"Product Launch","color":"#10B981"}],"type":"array","items":{"$ref":"#/components/schemas/CreateTagDto"}}},"required":["tags"]},"CreateManyTagsJobExecutionNewDto":{"type":"object","properties":{"tags":{"description":"List of tag job executions to create in a single batch. Must contain at least one item; each entry is validated individually.","example":[{"name":"important","color":"#3B82F6"},{"name":"archived","color":"#9CA3AF"}],"type":"array","items":{"$ref":"#/components/schemas/CreateTagJobExecutionNewDto"}},"confirmVectorization":{"type":"boolean","description":"Ignored. Semantic tags no longer index the project responses, so there is nothing to confirm.","deprecated":true,"example":true}},"required":["tags"]},"CreateQueryDto":{"type":"object","properties":{"query":{"type":"string","description":"The search query","example":"machine learning trends"},"language":{"type":"string","description":"Language code (BCP-47-style, from the supported allowlist). Examples: \"en\", \"fr\", \"zh-cn\", \"ro-MD\", \"yue\".","example":"en","enum":["en","es","fr","pt","de","it","tr","nl","pl","sq","ar","hy","az","ba","eu","be","bn","bho","bs","bg","yue","ca","zh-cn","hr","cs","da","et","fo","fi","gl","ka","el","gu","hi","hu","id","ga","ja","jv","kn","ks","kk","kok","ko","ky","lv","lt","ru","mk","mai","ms","mt","cmn","mr","mwr","nan","ro-MD","mn","cnr","ne","no","or","ps","fa","pa","raj","ro","sa","sat","sr","sd","si","sk","sl","sv","uk","ur","uz","vi","cy","wuu","th"]},"country":{"type":"string","description":"Country code (ISO 3166-1 alpha-2, uppercase, from the supported allowlist).","example":"US","enum":["AD","AE","AF","AG","AL","AM","AO","AR","AT","AU","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BN","BO","BR","BS","BT","BW","BZ","CA","CD","CF","CG","CH","CI","CL","CN","CM","CO","CR","CV","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","ER","ES","ET","FI","FJ","FM","FR","GA","GB","GD","GE","GH","GM","GN","GQ","GR","GT","GW","GY","HK","HN","HR","HT","HU","ID","IE","IL","IN","IQ","IS","IT","JM","JO","JP","KE","KG","KH","KI","KM","KR","KW","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MG","MH","MK","ML","MM","MN","MR","MT","MU","MV","MW","MX","MY","MZ","NA","NE","NG","NI","NL","NO","NP","NR","NZ","OM","PA","PE","PG","PH","PK","PL","PS","PT","PW","PY","QA","RO","RS","RW","SA","SB","SC","SD","SE","SG","SI","SK","SL","SM","SN","SO","SR","SS","SV","SZ","TD","TG","TH","TJ","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","US","UY","UZ","VA","VN","VU","WS","YE","ZA","ZM","ZW"]},"type":{"description":"The type of question the query asks: \"comparative\" (compares options), \"informative\" (seeks facts or how-to information) or \"perception\" (probes opinions about a brand).","allOf":[{"$ref":"#/components/schemas/QueryType"}]},"tagIds":{"description":"List of tag IDs to associate with this query","example":[1,2,3],"type":"array","items":{"type":"number"}}},"required":["query","language","country"]},"CreateTagDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tag. Must not start or end with a quote or apostrophe.","example":"feature"},"color":{"type":"string","description":"Color of the tag in hex format","example":"#3B82F6"},"groupId":{"type":"string","description":"ID of the query-taxonomy tag group to file the tag under, or null for ungrouped. Group assignment never triggers tag re-matching.","format":"uuid","nullable":true,"example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"}},"required":["name","color"]},"CreateTagGroupDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tag group, unique per project and taxonomy. Must not start or end with a quote or apostrophe.","example":"Selection criteria"},"tagType":{"type":"string","description":"Which tag taxonomy this folder organizes: \"query\" tags or \"execution\" tags. Immutable after creation.","enum":["query","execution"],"example":"query"},"color":{"type":"string","description":"Color of the tag group in hex format.","example":"#3B82F6"}},"required":["name","tagType"]},"CreateTagJobExecutionNewDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tag. Must not start or end with a quote or apostrophe.","example":"important"},"color":{"type":"string","description":"Color of the tag in hex format","example":"#3B82F6"},"matchingMode":{"type":"string","description":"How the tag is matched to responses: `exact` links only responses whose text contains the tag name (default), `semantic` links responses by meaning, using the name, description and exclusion.","enum":["exact","semantic"],"example":"exact"},"description":{"type":"string","description":"Semantic tags: what the tag covers. Changing it marks the tag for a history re-sync.","nullable":true,"maxLength":300,"example":"Checked baggage rules, weight limits and extra bag fees."},"exclusion":{"type":"string","description":"Semantic tags: what the tag does not cover. Changing it marks the tag for a history re-sync.","nullable":true,"maxLength":200,"example":"Cabin bags."},"confirmVectorization":{"type":"boolean","description":"Ignored. Semantic tags no longer index the project responses, so there is nothing to confirm.","deprecated":true,"example":true},"groupId":{"type":"string","description":"ID of the execution-taxonomy tag group to file the tag under, or null for ungrouped. Group assignment never triggers tag re-matching or re-embedding.","format":"uuid","nullable":true,"example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"}},"required":["name","color"]},"CustomMetricsBaseFilterDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"entityIds":{"description":"Optional entity ids passed by the dashboard when a \"view as\" brand is active. Custom metrics typically ignore this and rely on the `highlight` rule to mark the targeted row instead.","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6","7c9e6679-7425-40de-944b-e07fc1f90ae7"],"type":"array","items":{"type":"string"}},"bucketSize":{"type":"string","description":"Time bucket granularity for trend metrics (day/week/month). Defaults to day. Ignored by table-shaped metrics.","enum":["day","week","month"],"example":"day"}}},"DispatchRequestDto":{"type":"object","properties":{"metric":{"type":"string","description":"Metric identifier (matches `id` returned by GET /analytics/custom-metrics)","example":"sample-metric-table"},"filter":{"description":"Filter payload. Validated by the dispatcher against the metric-specific DTO class, which extends this base.","example":{"startDate":"2026-01-01","endDate":"2026-01-31"},"allOf":[{"$ref":"#/components/schemas/CustomMetricsBaseFilterDto"}]}},"required":["metric"]},"DrilldownEntitiesResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total number of AI responses for the selected model in the filtered scope (denominator for visibility).","example":500},"entities":{"description":"All detected entities for the selected model, ordered by presentIn descending.","type":"array","items":{"$ref":"#/components/schemas/DrilldownEntityPoint"}}},"required":["totalResponses","entities"]},"DrilldownEntityPoint":{"type":"object","properties":{"displayKey":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable entity name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project (i.e. the project's own brand or product).","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this entity is a configured competitor of the project.","example":false},"mentionCount":{"type":"number","description":"Total number of times this entity is mentioned on the selected model. Used as the numerator for share of voice.","example":42},"visibility":{"type":"number","description":"Visibility percentage — how often this entity appears in the selected model's AI responses. Formula: (presentIn / totalResponses) × 100, where presentIn = distinct responses mentioning this entity.","example":28},"shareOfVoice":{"type":"number","description":"Share of voice — this entity's portion of all entity mentions for the selected model. Formula: (mentionCount / total entity mentions for this model) × 100. Values across all entities sum to 100%.","example":15},"avgRanking":{"type":"number","description":"Weighted average position rank for this entity on the selected model. Lower values mean the entity tends to appear higher/earlier in responses.","example":2.5}},"required":["displayKey","displayName","isOwned","isPrimary","isCompetitor","mentionCount","visibility","shareOfVoice","avgRanking"]},"DrilldownSourcePoint":{"type":"object","properties":{"domain":{"type":"string","description":"Root domain name (e.g. reddit.com).","example":"example.com"},"resultCount":{"type":"number","description":"Number of distinct AI responses (for the selected model) that cited at least one page from this domain. A single response citing multiple pages from the same domain counts as 1.","example":50},"citationRate":{"type":"number","description":"Citation rate — how often this domain appears across the selected model's AI responses. Formula: (resultCount / totalResponses) × 100.","example":10},"pageCount":{"type":"number","description":"Total number of individual page/URL citations from this domain (not deduped). One AI response may cite multiple pages from the same domain, each counted separately.","example":75}},"required":["domain","resultCount","citationRate","pageCount"]},"DrilldownSourcesResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total number of AI responses for the selected model in the filtered scope (denominator for citationRate).","example":500},"sources":{"description":"Top source domains for the selected model, ordered by resultCount descending.","type":"array","items":{"$ref":"#/components/schemas/DrilldownSourcePoint"}}},"required":["totalResponses","sources"]},"EntitiesTimeseriesPoint":{"type":"object","properties":{"bucket":{"type":"string","description":"Start of the time bucket (ISO 8601). Granularity depends on the requested bucketSize (day/week/month).","example":"2025-01-01T00:00:00.000Z"},"displayKey":{"type":"string","description":"Unique identifier for the entity or entity group. In per-entity mode this is the canonical entity ID; in grouped mode it is the entity group ID (or entity ID if ungrouped).","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable name of the entity or entity group.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project (i.e. the project's own brand or product).","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this entity is a configured competitor of the project.","example":false},"totalResponses":{"type":"number","description":"Total number of AI responses in this time bucket (denominator for visibilityPct). Scoped by the request filters (project, date range, models, platforms, tags).","example":150},"presentIn":{"type":"number","description":"Number of AI responses in this bucket that mention the entity/group (numerator for visibilityPct). A response mentioning multiple variants of the same canonical entity is counted once.","example":42},"visibilityPct":{"type":"number","description":"Visibility percentage — how often this entity/group appears across AI responses in this bucket. Formula: (presentIn / totalResponses) × 100.","example":28},"avgPositionRank":{"type":"number","description":"Weighted average position rank for this entity in this time bucket. Lower values mean the entity appears earlier in AI responses. 0 if no position data.","example":2.5},"mentionCount":{"type":"number","description":"Total number of mention entries for this entity in this time bucket (raw count before dedup). Used to compute avgMentionsPerResult.","example":56},"sentimentScore":{"type":"number","description":"Average sentiment score for this entity across mentions in this time bucket. Scale: 0 (most negative) to 100 (most positive). Null when the bucket has no scored mentions.","example":72.3,"nullable":true},"avgMentionsPerResult":{"type":"number","description":"Average number of times this entity is mentioned per AI response that mentions it in this bucket. Formula: mentionCount / presentIn. Values > 1 indicate repeated prominence. Null when presentIn is 0.","example":1.33,"nullable":true}},"required":["bucket","displayKey","displayName","isOwned","isPrimary","isCompetitor","totalResponses","presentIn","visibilityPct","avgPositionRank","mentionCount","sentimentScore","avgMentionsPerResult"]},"EntityAliasResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"alias":{"type":"string"},"source":{"type":"string","enum":["llm","manual"]}},"required":["id","alias","source"]},"EntityDetailResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["brand","person","company","other"]},"level":{"type":"string","nullable":true,"description":"Tier inside the project's entity type (e.g. country or city); null for brands and untagged entities","example":"city"},"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"},"aliases":{"description":"Alternate name strings that resolve to this entity.","type":"array","items":{"$ref":"#/components/schemas/EntityAliasResponse"}},"mergedSources":{"description":"Separate entities merged into this one (their mentions roll up here; reversible via unmerge).","type":"array","items":{"$ref":"#/components/schemas/MergedEntityRef"}}},"required":["id","name","slug","type","isOwned","isPrimary","isCompetitor","isBlacklisted","domains","createdAt","updatedAt","aliases","mergedSources"]},"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"]},"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"]},"EntityGroupResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["group","division"],"description":"What this container is: a top-level \"group\" or a \"division\". Immutable."},"parent":{"type":"string","description":"Parent group ID. Set only on divisions that belong to a group; null on top-level groups and standalone divisions.","format":"uuid","nullable":true},"name":{"type":"string"},"slug":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","kind","name","slug","createdAt","updatedAt"]},"EntityModelVisibilityPoint":{"type":"object","properties":{"model":{"type":"string","description":"AI model name (e.g. gpt-4o, claude-3.5-sonnet).","example":"gpt-4o"},"totalResponses":{"type":"number","description":"Total number of AI responses for this model (denominator for visibilityPct). Scoped by the request filters (project, date range, platforms, tags).","example":500},"presentIn":{"type":"number","description":"Number of AI responses for this model that mention this entity (numerator for visibilityPct). After canonical entity deduplication.","example":120},"visibilityPct":{"type":"number","description":"Visibility percentage — how often this entity appears in this model's AI responses. Formula: (presentIn / totalResponses) × 100.","example":24}},"required":["model","totalResponses","presentIn","visibilityPct"]},"EntityResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"type":{"type":"string","enum":["brand","person","company","other"]},"level":{"type":"string","nullable":true,"description":"Tier inside the project's entity type (e.g. country or city); null for brands and untagged entities","example":"city"},"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"]},"EntityStanceDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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":"Entity (brand) id — canonical or a merged source.","example":"550e8400-e29b-41d4-a716-446655440000"},"stance":{"type":"string","description":"Stance to filter on.","enum":["chosen","mentioned","named","negative_mentioned","negative_named"]},"page":{"type":"number","description":"Page number (1-based). Default: 1.","example":1},"pageSize":{"type":"number","description":"Results per page. Default: 10, max: 50.","example":10}},"required":["entityId","stance"]},"EntityStanceResponse":{"type":"object","properties":{"responses":{"type":"array","items":{"$ref":"#/components/schemas/EntityStanceResponseItem"}},"page":{"$ref":"#/components/schemas/Paging"}},"required":["responses","page"]},"EntityStanceResponseItem":{"type":"object","properties":{"aiResponseId":{"type":"string"},"initiatedAt":{"type":"string","description":"When the response was generated (ISO 8601)."},"model":{"type":"string","nullable":true},"queryId":{"type":"string","nullable":true},"queryText":{"type":"string","nullable":true,"description":"The query prompt text."},"sentiment":{"type":"string","nullable":true,"enum":["positive","neutral","negative","mixed"]},"sentimentScore":{"type":"number","nullable":true,"description":"Entity sentiment score 1–100 in this response."},"stance":{"type":"string","enum":["chosen","mentioned","named","negative_mentioned","negative_named"]},"text":{"type":"string","nullable":true,"description":"Full AI response text."},"reasons":{"description":"The brand's theme evidence in this response.","type":"array","items":{"$ref":"#/components/schemas/StanceReason"}}},"required":["aiResponseId","initiatedAt","model","queryId","queryText","sentiment","sentimentScore","stance","text","reasons"]},"EntityTypeResponse":{"type":"object","properties":{"key":{"type":"string","enum":["brands","brands_and_products","countries_cities","organisations","people","places","facilities","events"],"description":"Stable key, as a project's entityType stores it","example":"countries_cities"},"displayName":{"type":"string","description":"Label for the type picker","example":"Countries & Cities"},"status":{"type":"string","enum":["available","coming_soon"],"description":"available: the organisation can create a project of this type now","example":"available"},"mentionVocab":{"type":"object","additionalProperties":{"type":"string"},"description":"Label of each mention stance, worded for this type","example":{"chosen":"Top pick","mentioned":"Favorably positioned","named":"Named","negative_mentioned":"Unfavorably positioned","negative_named":"Listed among the weaker options"}},"levelVocab":{"nullable":true,"description":"Tiers an entity of this type is tagged with (an entity's level), top-down; null when the type has none","example":["region","country","city"],"type":"array","items":{"type":"string"}}},"required":["key","displayName","status","mentionVocab","levelVocab"]},"EntityVisibilityEntity":{"type":"object","properties":{"displayKey":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable entity name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project (i.e. the project's own brand or product).","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this entity is a configured competitor of the project.","example":false},"models":{"description":"Per-model visibility scores for this entity. Each entry contains the model name, total responses, and visibility percentage.","type":"array","items":{"$ref":"#/components/schemas/EntityModelVisibilityPoint"}}},"required":["displayKey","displayName","isOwned","isPrimary","isCompetitor","models"]},"EntityVisibilityResponse":{"type":"object","properties":{"entities":{"description":"Entity visibility matrix — each entity has a nested array of per-model visibility scores. Entities are ordered by display name, models by model name within each entity.","type":"array","items":{"$ref":"#/components/schemas/EntityVisibilityEntity"}}},"required":["entities"]},"FanOutForQueryPoint":{"type":"object","properties":{"fanOutText":{"type":"string","description":"The search query text the AI ran.","example":"HubSpot vs Salesforce pricing comparison"},"occurrenceCount":{"type":"number","description":"Number of AI responses for this query that produced this specific fan-out.","example":8},"rate":{"type":"number","description":"Occurrence rate within this query — how often this fan-out appears across AI responses for the query. Formula: (occurrenceCount / totalResponsesForQuery) × 100.","example":18.18}},"required":["fanOutText","occurrenceCount","rate"]},"FanOutTopPoint":{"type":"object","properties":{"fanOutText":{"type":"string","description":"The search query text the AI ran.","example":"HubSpot vs Salesforce pricing comparison"},"occurrenceCount":{"type":"number","description":"Number of AI responses that produced this fan-out (across all queries and models).","example":12},"rate":{"type":"number","description":"Occurrence rate — how often this fan-out appears across AI responses that have fan-outs. Formula: (occurrenceCount / totalWithFanOuts) × 100.","example":27.27}},"required":["fanOutText","occurrenceCount","rate"]},"FanOutsByQueryDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"sort":{"description":"Sort order. Allowed fields: fanOutCount, uniqueFanOutCount, avgPerExecution.","example":[{"field":"fanOutCount","direction":"DESC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}},"page":{"type":"number","description":"Page number (1-based).","example":1},"pageSize":{"type":"number","description":"Results per page. Default: 50, max: 200.","example":50}}},"FanOutsByQueryPoint":{"type":"object","properties":{"queryId":{"type":"string","description":"Query UUID.","example":"550e8400-e29b-41d4-a716-446655440000"},"queryText":{"type":"string","description":"The query (prompt) text.","example":"What is the best CRM software for small business?"},"type":{"description":"The type of question the query asks. Null for queries that have not been classified.","nullable":true,"allOf":[{"$ref":"#/components/schemas/QueryType"}]},"fanOutCount":{"type":"number","description":"Total fan-out entries for this query.","example":45},"uniqueFanOutCount":{"type":"number","description":"Number of unique fan-out texts for this query (deduplicated by hash).","example":18},"avgPerExecution":{"type":"number","description":"Average number of fan-outs per AI response with fan-outs, for this query. 0 if there are none.","example":3.2}},"required":["queryId","queryText","type","fanOutCount","uniqueFanOutCount","avgPerExecution"]},"FanOutsByQueryResponse":{"type":"object","properties":{"queries":{"description":"Paginated list of queries that produced fan-outs, with per-query statistics.","type":"array","items":{"$ref":"#/components/schemas/FanOutsByQueryPoint"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["queries","page"]},"FanOutsFilterDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"limit":{"type":"number","description":"Max fan-outs to return. Used by /top endpoint, ignored by /overview. Default: 50, max: 200.","example":50}}},"FanOutsForQueryDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"page":{"type":"number","description":"Page number (1-based).","example":1},"pageSize":{"type":"number","description":"Results per page. Default: 50, max: 200.","example":50}}},"FanOutsForQueryResponse":{"type":"object","properties":{"totalResponsesForQuery":{"type":"number","description":"Number of distinct AI responses for this query that produced at least one fan-out. Used as the denominator for the rate calculation.","example":44},"fanOuts":{"description":"Fan-outs for this query, ordered by occurrenceCount descending.","type":"array","items":{"$ref":"#/components/schemas/FanOutForQueryPoint"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["totalResponsesForQuery","fanOuts","page"]},"FanOutsOverviewResponse":{"type":"object","properties":{"totalFanOuts":{"type":"number","description":"Total number of fan-out entries in the filtered scope. Each AI response may produce multiple fan-outs, so this can exceed the number of responses.","example":1247},"uniqueFanOuts":{"type":"number","description":"Number of unique fan-out texts (deduplicated by text). The same text in several responses counts as 1.","example":342},"avgPerExecution":{"type":"number","description":"Average number of fan-outs per AI response with fan-outs. 0 if no fan-outs exist in scope.","example":3.6}},"required":["totalFanOuts","uniqueFanOuts","avgPerExecution"]},"FanOutsTopResponse":{"type":"object","properties":{"totalWithFanOuts":{"type":"number","description":"Number of distinct AI responses that produced at least one fan-out in the filtered scope. Used as the denominator for the rate calculation.","example":44},"fanOuts":{"description":"Top fan-outs ordered by occurrenceCount descending, limited by the `limit` parameter.","type":"array","items":{"$ref":"#/components/schemas/FanOutTopPoint"}}},"required":["totalWithFanOuts","fanOuts"]},"GetItemsDto":{"type":"object","properties":{"entityIds":{"description":"Filter by brand entity IDs.","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}},"productIds":{"description":"Filter by product IDs.","example":["7c9e6679-7425-40de-944b-e07fc1f90ae7"],"type":"array","items":{"type":"string"}},"search":{"type":"string","description":"Search by raw product name (partial match, case-insensitive).","example":"iPhone"},"externalId":{"type":"string","description":"Filter by exact external ID.","example":"product-123-abc"},"mappingStatus":{"type":"array","description":"Filter by product-mapping status. \"unknown\" = a brand is assigned but no specific product; \"not_matched\" = neither a brand nor a product. Omit to return all items.","example":["unknown"],"items":{"type":"string","enum":["unknown","not_matched"]}}}},"ImportEntitiesDto":{"type":"object","properties":{"rows":{"description":"The rows to upsert, in file order. The response carries one result per row at the same index.","example":[{"name":"Samsung","isCompetitor":true,"group":"Tech Companies"}],"type":"array","items":{"$ref":"#/components/schemas/ImportEntityRowDto"}},"dryRun":{"type":"boolean","description":"Report what would happen without writing anything.","example":false}},"required":["rows"]},"ImportEntitiesResponse":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"True when nothing was written.","example":false},"created":{"type":"number","example":3},"updated":{"type":"number","example":118},"unchanged":{"type":"number","example":12},"failed":{"type":"number","example":1},"results":{"description":"One entry per submitted row, in submission order.","type":"array","items":{"$ref":"#/components/schemas/ImportEntityRowResultResponse"}}},"required":["dryRun","created","updated","unchanged","failed","results"]},"ImportEntityRowDto":{"type":"object","properties":{"id":{"type":"string","description":"Entity id from the entities export. Authoritative when present; a different `name` renames the entity.","format":"uuid","example":"019daf29-0000-7000-8000-0000000000a1"},"name":{"type":"string","description":"Entity name. Required when `id` is absent, and then also the match key.","example":"Samsung"},"type":{"type":"string","description":"Type/category. Defaults to brand on creation.","enum":["brand","person","company","other"]},"aliases":{"description":"Aliases to add. Never removes one; an alias already owned by another entity is left alone.","example":["Samsung Electronics"],"type":"array","items":{"type":"string"}},"domains":{"description":"Complete set of domains for this entity, normalised to registrable root domains. Unlike aliases this REPLACES the entity's set, so a domain the list omits is unmapped, and an empty array clears them all. The exported cell already carries the full set, which is what makes a round trip lossless. Absent leaves them untouched, and a blank spreadsheet cell parses to absent rather than to an empty array, so a stale export cannot wipe them by omission.","example":["hubspot.com","hubspot.fr"],"type":"array","items":{"type":"string"}},"group":{"type":"string","description":"Name of the top-level group to place the entity in. Must already exist; an unknown name fails the row.","example":"Tech Companies"},"division":{"type":"string","description":"Name of the division to place the entity in, inside `group` when both are given. Must already exist.","example":"EMEA"},"isOwned":{"type":"boolean","description":"Mark entity as owned by the project","example":false},"isCompetitor":{"type":"boolean","description":"Mark entity as a competitor","example":true},"isBlacklisted":{"type":"boolean","description":"Mark entity as blacklisted (excludes it from analysis but preserves history)","example":false},"isPrimary":{"type":"boolean","description":"Mark the entity as the project's primary brand. At most one row per request may set this true.","example":false}}},"ImportEntityRowResultResponse":{"type":"object","properties":{"index":{"type":"number","description":"Zero-based index of the row in the submitted batch.","example":0},"action":{"type":"string","enum":["created","updated","unchanged","failed"]},"entityId":{"type":"string","description":"The entity this row resolved to. Absent on failure.","format":"uuid"},"error":{"type":"string","enum":["no-identity","name-has-no-slug","entity-not-found","duplicate-identity","ambiguous-name","entity-is-merged","group-not-found","multiple-primary","slug-conflict"]},"detail":{"type":"string","description":"Human-readable context for the failure: the conflicting name, the unknown group, or the other row index.","example":"no group named \"Competitors UE\""}},"required":["index","action"]},"ImportMergeEdgeDto":{"type":"object","properties":{"id":{"type":"string","description":"The entity to merge away.","format":"uuid","example":"019daf29-0000-7000-8000-0000000000b1"},"mergedIntoId":{"type":"string","description":"The entity it should be merged into. Must be an id, never a name.","format":"uuid","example":"019daf29-0000-7000-8000-0000000000a1"}},"required":["id","mergedIntoId"]},"ImportMergeEdgeResultResponse":{"type":"object","properties":{"index":{"type":"number","description":"Zero-based index of the edge in the submitted batch.","example":0},"action":{"type":"string","enum":["merged","unchanged","failed"],"example":"merged"},"resolvedParentId":{"type":"string","description":"The survivor the entity actually ended up under. Differs from the requested mergedIntoId when the file described a chain, or when that parent was itself already merged, the graph is always flattened to its root.","format":"uuid","example":"019daf29-0000-7000-8000-0000000000a1"},"error":{"type":"string","enum":["self-reference","cycle","entity-not-found","parent-not-found","conflicting-parent"]},"detail":{"type":"string","description":"Human-readable context for the failure.","example":"b1 → a1 closes a loop"}},"required":["index","action"]},"ImportMergeEntitiesDto":{"type":"object","properties":{"edges":{"description":"Every merge edge in the file, in one request. Chains and cycles are resolved across the whole set.","example":[{"id":"019daf29-0000-7000-8000-0000000000b1","mergedIntoId":"019daf29-0000-7000-8000-0000000000a1"}],"type":"array","items":{"$ref":"#/components/schemas/ImportMergeEdgeDto"}},"dryRun":{"type":"boolean","description":"Report what would happen without merging anything.","example":true}},"required":["edges"]},"ImportMergeEntitiesResponse":{"type":"object","properties":{"dryRun":{"type":"boolean","description":"True when nothing was written.","example":false},"merged":{"type":"number","description":"Entities merged away.","example":42},"unchanged":{"type":"number","description":"Edges that were already satisfied.","example":3},"failed":{"type":"number","description":"Edges rejected.","example":1},"survivors":{"type":"number","description":"Distinct survivors this batch resolved to, the number of merge operations performed.","example":7},"results":{"description":"One entry per submitted edge, in submission order.","type":"array","items":{"$ref":"#/components/schemas/ImportMergeEdgeResultResponse"}}},"required":["dryRun","merged","unchanged","failed","survivors","results"]},"JenModelsResponse":{"type":"object","properties":{"models":{"description":"Unique AI model names used by job executions in this project.","example":["gpt-4o","gemini-1.5-pro"],"type":"array","items":{"type":"string"}}},"required":["models"]},"JobCreatedByResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the user who created the job.","example":"01234567-89ab-cdef-0123-456789abcdef"},"firstName":{"type":"string","description":"First name of the user who created the job.","example":"Jane"},"lastName":{"type":"string","description":"Last name of the user who created the job.","example":"Doe"},"email":{"type":"string","description":"Email address of the user who created the job.","example":"jane.doe@example.com"}},"required":["firstName","lastName","email"]},"JobExecutionDetailResponse":{"type":"object","properties":{"jobExecutionId":{"type":"string","format":"uuid","description":"Job execution (run) ID.","example":"3f1a7b2c-9d4e-4f6a-8b1c-2e5f7a9d0c11"},"aiResponseId":{"type":"string","format":"uuid","description":"AI response ID produced by this run.","example":"a8d2e4f0-1b3c-4d5e-9f8a-7c6b5a4d3e2f"},"queryId":{"type":"string","format":"uuid","description":"Query ID this run answered, if any.","example":"c2b4d6e8-0a1f-4c3d-8e7b-6a5f4d3c2b1a"},"jobId":{"type":"string","format":"uuid","description":"Job ID this run belongs to.","example":"d9c8b7a6-5f4e-4d3c-9b2a-1e0f9d8c7b6a"},"initiatedAt":{"format":"date-time","type":"string","description":"When the response was initiated.","example":"2026-06-08T10:15:30.000Z"},"createdAt":{"format":"date-time","type":"string","description":"When the response row was created.","example":"2026-06-08T10:15:31.000Z"},"model":{"type":"string","description":"AI model used.","example":"gpt-4o"},"country":{"type":"string","description":"Country code.","example":"US"},"language":{"type":"string","description":"Language code.","example":"en"},"status":{"type":"string","enum":["pending","success","failed","retrying"],"description":"Run status."},"executionNumber":{"type":"number","description":"Execution number within the job (retry counter).","example":1},"hasSources":{"type":"boolean","description":"Whether the response includes source citations.","example":true},"hasShopping":{"type":"boolean","description":"Whether the response includes shopping products.","example":false},"hasAds":{"type":"boolean","description":"Whether the response rendered sponsored ads.","example":false},"sources":{"description":"Source citations found in this response.","type":"array","items":{"$ref":"#/components/schemas/QueryResultSourceItem"}},"entities":{"description":"Entities mentioned in this response (after canonical dedup).","type":"array","items":{"$ref":"#/components/schemas/QueryResultEntityItem"}}},"required":["jobExecutionId","aiResponseId","jobId","initiatedAt","createdAt","model","status","executionNumber","hasSources","hasShopping","hasAds","sources","entities"]},"JobLastExecutionDateResponse":{"type":"object","properties":{"lastExecutionDate":{"format":"date-time","type":"string","description":"The date of the last job execution for this project, or null if no executions exist.","example":"2026-04-30T12:00:00.000Z","nullable":true}},"required":["lastExecutionDate"]},"JobResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the job.","example":"01234567-89ab-cdef-0123-456789abcdef"},"project":{"description":"Project the job belongs to. Returned as the project identifier (UUID) when not populated, or as the full project object when expanded.","oneOf":[{"type":"string","format":"uuid"},{"$ref":"#/components/schemas/ProjectResponse"}],"example":"01234567-89ab-cdef-0123-456789abcdef"},"createdBy":{"description":"User who created the job. May be null when the creator is unknown or no longer available.","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/JobCreatedByResponse"}]},"totalExecutions":{"type":"number","description":"Total number of executions associated with the job.","example":100},"pendingExecutions":{"type":"number","description":"Number of executions that are still pending processing.","example":10},"retryingExecutions":{"type":"number","description":"Number of executions currently being retried after a failure.","example":2},"successExecutions":{"type":"number","description":"Number of executions that completed successfully.","example":80},"failedExecutions":{"type":"number","description":"Number of executions that failed.","example":8},"status":{"type":"string","enum":["pending","processing","syncing","completed","failed","partial_failed"],"description":"Overall status of the job, derived from the state of its executions. syncing: every execution has finished and the results are still being copied to the analytics store; it then turns completed or partial_failed.","example":"processing"},"createdAt":{"format":"date-time","type":"string","description":"Timestamp at which the job was created.","example":"2026-06-08T12:00:00.000Z"},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp at which the job was last updated.","example":"2026-06-08T12:30:00.000Z"}},"required":["id","project","totalExecutions","pendingExecutions","retryingExecutions","successExecutions","failedExecutions","status","createdAt","updatedAt"]},"LinkManyTagsDto":{"type":"object","properties":{"tagIds":{"description":"IDs of the tags to link","example":[1,2,3],"type":"array","items":{"type":"number"}},"queryIds":{"description":"IDs of the queries to link the tags to","example":["0199c3a4-7f2b-7c31-9d55-2b0e4f6a8c11","0199c3a4-8d10-7e42-b6a7-91c3f5027d64"],"type":"array","items":{"type":"string"}}},"required":["tagIds","queryIds"]},"LinkManyTagsJobExecutionNewDto":{"type":"object","properties":{"tagIds":{"description":"UUIDs of the tags to link","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"type":"array","items":{"type":"string"}},"jobExecutionIds":{"description":"UUIDs of the job executions to link the tags to","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"type":"array","items":{"type":"string"}}},"required":["tagIds","jobExecutionIds"]},"ListCustomMetricsResponse":{"type":"object","properties":{"metrics":{"type":"array","items":{"$ref":"#/components/schemas/MetricInfoResponse"}}},"required":["metrics"]},"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},"isOwnedOrCompetitor":{"type":"boolean","description":"Filter entities by whether they are primary, owned or competitors. `true` returns only those entities.","example":true},"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"}}}},"ListEntityGroupsDto":{"type":"object","properties":{"name":{"type":"string","description":"Filter entity groups by name using a case-insensitive partial match.","example":"Competitors"},"kind":{"type":"string","description":"Filter by container kind: \"group\" for top-level groups, \"division\" for divisions. Omit to list both.","enum":["group","division"]},"parentId":{"type":"string","description":"Filter to the divisions of a given group, by group ID.","example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"},"sort":{"description":"Sorting criteria for the returned entity groups. Supports sorting by \"name\" and \"createdAt\". Defaults to sorting by name in ascending order.","example":[{"field":"name","direction":"ASC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"ListJobsDto":{"type":"object","properties":{"status":{"type":"string","description":"Filter the jobs by their processing status. A syncing job matches completed or partial_failed.","enum":["pending","processing","completed","failed","partial_failed"],"example":"completed"},"createdBy":{"type":"string","description":"Filter the jobs by the identifier of the user who created them.","example":"550e8400-e29b-41d4-a716-446655440000"},"sort":{"description":"Sorting criteria for the returned jobs. Each entry pairs a sortable field (createdAt, updatedAt or status) with a direction (ASC or DESC). Defaults to sorting by creation date descending.","example":[{"field":"createdAt","direction":"DESC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"ListQueryDto":{"type":"object","properties":{"query":{"type":"string","description":"Free-text search filter applied to the query text. Performs a case-insensitive partial match against the query name.","example":"climate change"},"languages":{"type":"array","description":"Filter queries by language. Accepts one or more supported language codes; only queries matching any of the provided codes are returned.","example":["en","fr"],"items":{"type":"string","enum":["en","es","fr","pt","de","it","tr","nl","pl","sq","ar","hy","az","ba","eu","be","bn","bho","bs","bg","yue","ca","zh-cn","hr","cs","da","et","fo","fi","gl","ka","el","gu","hi","hu","id","ga","ja","jv","kn","ks","kk","kok","ko","ky","lv","lt","ru","mk","mai","ms","mt","cmn","mr","mwr","nan","ro-MD","mn","cnr","ne","no","or","ps","fa","pa","raj","ro","sa","sat","sr","sd","si","sk","sl","sv","uk","ur","uz","vi","cy","wuu","th"]}},"countries":{"type":"array","description":"Filter queries by country. Accepts one or more supported country codes; only queries matching any of the provided codes are returned.","example":["BE","FR"],"items":{"type":"string","enum":["AD","AE","AF","AG","AL","AM","AO","AR","AT","AU","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BN","BO","BR","BS","BT","BW","BZ","CA","CD","CF","CG","CH","CI","CL","CN","CM","CO","CR","CV","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","ER","ES","ET","FI","FJ","FM","FR","GA","GB","GD","GE","GH","GM","GN","GQ","GR","GT","GW","GY","HK","HN","HR","HT","HU","ID","IE","IL","IN","IQ","IS","IT","JM","JO","JP","KE","KG","KH","KI","KM","KR","KW","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MG","MH","MK","ML","MM","MN","MR","MT","MU","MV","MW","MX","MY","MZ","NA","NE","NG","NI","NL","NO","NP","NR","NZ","OM","PA","PE","PG","PH","PK","PL","PS","PT","PW","PY","QA","RO","RS","RW","SA","SB","SC","SD","SE","SG","SI","SK","SL","SM","SN","SO","SR","SS","SV","SZ","TD","TG","TH","TJ","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","US","UY","UZ","VA","VN","VU","WS","YE","ZA","ZM","ZW"]}},"types":{"type":"array","description":"Filter queries by type. Accepts one or more types; only queries matching any of the provided types are returned. Untyped queries are excluded when this filter is set.","items":{"$ref":"#/components/schemas/QueryType"}},"hasRecurrenceSetting":{"type":"boolean","description":"Filter queries by whether they are linked to a recurrence setting. `true` returns only linked (recurring) queries; `false` returns only unlinked queries.","example":false},"recurrenceSettingIds":{"description":"Filter to queries that are EITHER unassigned (no recurrence setting) OR linked to one of the given recurrence setting ids. Omit to apply no such filter.","example":["018f3a2b-7c4d-7e1a-9b2c-3d4e5f6a7b8c"],"type":"array","items":{"type":"string"}},"tagIds":{"description":"Filter queries by associated tag identifiers. Combined according to tagMode. An empty list matches no query.","example":[12,34],"type":"array","items":{"type":"number"}},"tagGroupIds":{"description":"Filter queries by tag group IDs. A group matches queries linked to any tag filed under it. Combined with tagIds according to tagMode.","example":["018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"],"type":"array","items":{"type":"string"}},"tagMode":{"type":"string","description":"How tagIds and tagGroupIds combine. \"and\" (default): every tag, and at least one tag of each group. \"or\": any tag, or any tag of any group.","enum":["and","or"]},"tagNames":{"description":"Filter queries by associated tag names. Case- and accent-insensitive partial match: returns queries linked to any tag whose name contains one of the terms.","example":["politics","economy"],"type":"array","items":{"type":"string"}},"sort":{"description":"Sorting options for the result set. Each entry specifies a field and direction. Sortable fields are \"query\" and \"updatedAt\". Defaults to sorting by query ascending.","example":[{"field":"query","direction":"ASC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"ListSourceCategoriesDto":{"type":"object","properties":{"label":{"type":"string","description":"Filter source categories by their label using a case-insensitive partial match.","example":"News"},"sort":{"description":"Sorting criteria for the source categories list. Each entry specifies a field to sort by (allowed: \"label\", \"slug\") and a direction (\"ASC\" or \"DESC\"). Defaults to sorting by label ascending.","example":[{"field":"label","direction":"ASC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"ListTagDto":{"type":"object","properties":{"name":{"type":"string","description":"Filter tags by name using a case-insensitive partial match.","example":"branding"},"with_queries_count":{"type":"boolean","description":"Include the count of queries associated with each tag","example":true},"sort":{"description":"Sorting options for the tag list. Currently only the \"name\" field is sortable. Defaults to ascending order by name.","example":[{"field":"name","direction":"ASC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"ListTagJobExecutionNewDto":{"type":"object","properties":{"name":{"type":"string","description":"Case-insensitive partial match filter applied to the tag job execution name.","example":"monthly-tagging"},"matchingMode":{"type":"string","enum":["exact","semantic"],"description":"Only tags with this matching mode: `exact` or `semantic`. Omit to list both.","example":"semantic"},"sort":{"description":"Sorting options for the result set. Only the \"name\" field is sortable; defaults to ascending order by name.","example":[{"field":"name","direction":"ASC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"LocaleSource":{"type":"string","enum":["runs","config"]},"MerchantItem":{"type":"object","properties":{"name":{"type":"string","description":"Merchant display name.","example":"Amazon"},"domain":{"type":"string","description":"Merchant domain (e.g. amazon.com). Null if not set.","example":"amazon.com","nullable":true}},"required":["name","domain"]},"MergeEntitiesDto":{"type":"object","properties":{"targetId":{"type":"string","description":"The entity ID to merge into (target).","example":"3f29c1a4-1b2c-4e7d-9a8b-0c1d2e3f4a5b"},"sourceIds":{"description":"Entity IDs to merge into the target (sources). The target id is ignored if present, and duplicates are collapsed.","example":["a1b2c3d4-e5f6-4789-90ab-cdef12345678","b2c3d4e5-f6a7-4890-81bc-def234567890"],"type":"array","items":{"type":"string"}}},"required":["targetId","sourceIds"]},"MergedEntityRef":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"]},"MetricAxisSpec":{"type":"object","properties":{"key":{"type":"string","description":"Point key carrying this axis value"},"label":{"type":"string"},"type":{"type":"string","enum":["date","number","percent"],"description":"Axis value type. 'percent' is a number formatted with a '%' suffix."}},"required":["key","label","type"]},"MetricColumnSpec":{"type":"object","properties":{"key":{"type":"string","description":"Row key this column reads from"},"label":{"type":"string","description":"Human-readable header label"},"type":{"type":"string","enum":["text","number","percent","entity","date"]},"decimals":{"type":"number","description":"Decimal places for `number` / `percent` columns"},"nullLabel":{"type":"string","description":"Rendered in place of null/undefined values","example":"—"},"tooltip":{"type":"string","description":"Explanatory copy shown on hover over the column header. Generic renderers surface it as a header tooltip; omit for self-evident columns."},"hidden":{"type":"boolean","description":"Auxiliary column carrying a component value (not for display); generic renderers should skip it"}},"required":["key","label","type"]},"MetricDefaultSort":{"type":"object","properties":{"column":{"type":"string","description":"Column key to sort by initially"},"order":{"type":"string","enum":["asc","desc"]}},"required":["column","order"]},"MetricHighlightRule":{"type":"object","properties":{"column":{"type":"string","description":"Column key the rule applies to. For 'max'/'min' rules this is a numeric column; for 'entity' it is an `entity`-typed column."},"rule":{"type":"string","enum":["max","min","entity"],"description":"How to pick the highlighted row. 'max'/'min' pick the row with the extremum value in `column`. 'entity' delegates to the frontend, which highlights the active 'view as' brand (if set) or otherwise the primary-flagged entity."}},"required":["column","rule"]},"MetricInfoResponse":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"shape":{"type":"string","enum":["table","timeseries"]},"slot":{"type":"string","description":"Slot on a host page where this metric should be rendered. e.g. \"overview.bottom\"."}},"required":["id","displayName","shape","slot"]},"MetricSeriesSpec":{"type":"object","properties":{"key":{"type":"string","description":"Point key carrying this series value"},"label":{"type":"string"},"color":{"type":"string","description":"Color hint (semantic palette token, e.g. \"primary\")"},"hidden":{"type":"boolean","description":"Auxiliary series carrying a component value (not for charting); generic renderers should skip it"}},"required":["key","label"]},"ModelTimeseriesV1Point":{"type":"object","properties":{"bucket":{"type":"string","description":"Start of the time bucket (ISO 8601). Granularity depends on the requested bucketSize (day/week/month).","example":"2025-01-01T00:00:00.000Z"},"model":{"type":"string","description":"AI model name (e.g. gpt-4o, claude-3.5-sonnet).","example":"gpt-4o"},"value":{"type":"number","description":"Metric value for this model in this bucket. Meaning depends on `metric`: visibility/sov/citation are percentages (higher is better); position is an average position rank (lower is better).","example":28},"metric":{"type":"string","description":"The metric this value represents (echoed from the request).","enum":["citation","position","sov","visibility"],"example":"visibility"}},"required":["bucket","model","value","metric"]},"ModelsDrilldownDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"model":{"type":"string","description":"The specific AI model to drill down into (e.g. \"gpt-4o\")","example":"gpt-4o"},"entityIds":{"description":"Ignored by the drill-down endpoints.","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}}},"required":["model"]},"ModelsFilterDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"entityIds":{"description":"Entities to measure. Defaults to the primary entities on platform-details, and to every entity of `entityTypes` on entity-visibility.","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}}}},"ModelsTimeseriesV1Dto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"bucketSize":{"type":"string","description":"Time bucket granularity","enum":["day","week","month"],"example":"day"},"entityIds":{"description":"Override entity IDs for visibility/SoV numerator (defaults to primary entities)","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}},"metric":{"type":"string","description":"Which metric to compute per bucket and model. Required.","enum":["citation","position","sov","visibility"],"example":"visibility"}},"required":["bucketSize","metric"]},"OrganisationConfigDto":{"type":"object","properties":{"logoUrlDark":{"type":"string","description":"Bucket link to the organisation logo for dark theme","example":"https://example.com/logo-dark.svg"},"logoUrlLight":{"type":"string","description":"Bucket link to the organisation logo for light theme","example":"https://example.com/logo-light.svg"}}},"OrganisationResponseWithIndirect":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the organisation","example":"01234567-89ab-cdef-0123-456789abcdef"},"name":{"type":"string","description":"Name of the organisation","example":"My Company"},"slug":{"type":"string","description":"Slug of the organisation","example":"my-organisation"},"isDirectMember":{"type":"boolean","description":"Whether the user is a direct member of the organisation","example":true},"config":{"description":"Organisation configuration details","allOf":[{"$ref":"#/components/schemas/OrganisationConfigDto"}]},"role":{"type":"string","description":"Role of the user in the organisation (if direct member)","enum":["org_admin","org_editor","org_viewer","super_org_admin","super_viewer"],"example":"org_admin"},"parentOrganisationId":{"type":"string","description":"Parent organisation id when this org is a sub-org. Absent for root orgs.","example":"01234567-89ab-cdef-0123-456789abcdef"},"billingMode":{"type":"string","description":"Billing mode for the org. Absent on sub-orgs (inherited from parent).","enum":["stripe_self_serve","stripe_partner","partner_invoice"]},"status":{"type":"string","description":"Account status (active / hard_suspended / frozen)","enum":["active","hard_suspended","frozen"],"example":"active"},"isSuperOrg":{"type":"boolean","description":"True iff this org has at least one child sub-org (i.e. is a super-org)","example":false},"features":{"description":"Client-visible entitlements granted to the org (e.g. model-gating keys). Empty when none.","example":["chat-latest"],"type":"array","items":{"type":"string"}}},"required":["id","name","isDirectMember","status","isSuperOrg","features"]},"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"]},"PagingResponse":{"type":"object","properties":{"page":{"$ref":"#/components/schemas/Paging"}},"required":["page"]},"PlatformDetailsPoint":{"type":"object","properties":{"model":{"type":"string","description":"AI model name (e.g. gpt-4o, claude-3.5-sonnet).","example":"gpt-4o"},"totalResponses":{"type":"number","description":"Total number of AI responses for this model (denominator for visibilityPct). Scoped by the request filters (project, date range, platforms, tags).","example":500},"presentIn":{"type":"number","description":"Number of AI responses for this model that mention the selected entities (numerator for visibilityPct). After canonical entity deduplication.","example":150},"visibilityPct":{"type":"number","description":"Visibility percentage — how often the selected entities appear in this model's AI responses. Formula: (presentIn / totalResponses) × 100.","example":30},"avgPositionRank":{"type":"number","description":"Weighted average position rank for the selected entities across this model's responses. Lower values mean the entity tends to appear higher/earlier in responses.","example":2.5},"mentionCount":{"type":"number","description":"Total number of times the selected entities are mentioned on this model. Used as the numerator for share of voice.","example":200},"totalMentions":{"type":"number","description":"Total mention count across all non-blacklisted entities for this model (denominator for shareOfVoice). Includes all entities, not just the selected ones.","example":800},"shareOfVoice":{"type":"number","description":"Share of voice — the selected entities' portion of all entity mentions for this model. Formula: (mentionCount / totalMentions) × 100.","example":25}},"required":["model","totalResponses","presentIn","visibilityPct","avgPositionRank","mentionCount","totalMentions","shareOfVoice"]},"PlatformDetailsResponse":{"type":"object","properties":{"models":{"description":"Per-model platform details with visibility, position rank, and share of voice for the selected entities. Ordered by totalResponses descending.","type":"array","items":{"$ref":"#/components/schemas/PlatformDetailsPoint"}}},"required":["models"]},"ProjectCustomFilterDto":{"type":"object","properties":{"type":{"type":"string","example":"tag-group","description":"Filter kind, e.g. 'tag-group' or 'continent'."},"id":{"type":"string","example":"01234567-89ab-cdef-0123-456789abcdef","description":"Target id: a tag-group uuid, or the continent label."}},"required":["type","id"]},"ProjectResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the project","example":"01234567-89ab-cdef-0123-456789abcdef"},"name":{"type":"string","description":"Name of the project","example":"My Project"},"slug":{"type":"string","description":"Slug of the project","example":"my-project"},"description":{"type":"string","description":"Description of the project","example":"My Project Description"},"industry":{"type":"string","description":"Industry of the project","example":"Technology"},"website":{"type":"string","description":"Website of the project","example":"https://www.mentionlab.io"},"entityType":{"type":"string","enum":["brands","brands_and_products","countries_cities","organisations","people","places","facilities","events"],"description":"What the project tracks; GET /entity-types gives its labels","example":"brands"},"analysisInstructions":{"type":"string","nullable":true,"description":"Extra instructions added to the analysis of the project's answers","example":"Do not count retailers or marketplaces as brands."},"organisation":{"type":"object","description":"Organisation that owns this project","example":"01234567-89ab-cdef-0123-456789abcdef"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp","example":"2021-01-01T00:00:00.000Z"},"currentPo":{"type":"string","description":"Active purchase order reference for this project.","example":"PO-2026-Q2-1234"},"themeAnalysisEnabled":{"type":"boolean","description":"Whether the async Brand Perception & Intelligence theme-analysis batch is enabled for this project.","example":false},"themeLanguage":{"type":"string","description":"Theme language for this project: a language code forces a monolingual taxonomy, 'auto' follows each answer.","example":"en"},"themeClusteringConfig":{"description":"Advanced per-project theme-clustering threshold overrides; absent knobs use the defaults.","allOf":[{"$ref":"#/components/schemas/ThemeClusteringConfigDto"}]},"settings":{"description":"Free-form per-project settings owned by the frontend (e.g. saved custom filters).","allOf":[{"$ref":"#/components/schemas/ProjectSettingsDto"}]}},"required":["id","name","entityType","organisation","updatedAt"]},"ProjectSettingsDto":{"type":"object","properties":{"customFilters":{"description":"Saved custom filters (tag-group / continent / …).","example":[{"type":"tag-group","id":"01234567-89ab-cdef-0123-456789abcdef"},{"type":"continent","id":"Europe"}],"type":"array","items":{"$ref":"#/components/schemas/ProjectCustomFilterDto"}}}},"ProviderRestrictionsMapResponseDto":{"type":"object","properties":{"provider":{"type":"string","example":"openai","description":"Provider name (e.g., openai, anthropic)"},"model":{"type":"string","example":"ai-mode","description":"Specific model identifier for the provider"},"allowedCountries":{"example":["US","FR"],"description":"List of allowed ISO 3166-1 alpha-2 country codes","type":"array","items":{"type":"string"}}},"required":["allowedCountries"]},"QueriesStatsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityIds":{"description":"Entity IDs for the project brand (defaults to primary non-blacklisted)","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}}}},"QueriesStatsResponse":{"type":"object","properties":{"queries":{"description":"Per-query statistics with brand metrics and source presence.","type":"array","items":{"$ref":"#/components/schemas/QueryStatsPoint"}}},"required":["queries"]},"QueryDetailDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"entityIds":{"description":"Entity IDs for brand-scoped metrics. Defaults to project brand.","example":["3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d"],"type":"array","items":{"type":"string"}}}},"QueryDetailEntitiesResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total number of AI responses for this query in the filtered scope (denominator for visibility).","example":42},"entities":{"description":"All detected entities for this query, ordered by presence (how often they appear in AI responses) descending.","type":"array","items":{"$ref":"#/components/schemas/QueryDetailEntityPoint"}}},"required":["totalResponses","entities"]},"QueryDetailEntityPoint":{"type":"object","properties":{"displayKey":{"type":"string","description":"Canonical entity ID. When aliases are merged, all variants resolve to this single key.","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable entity name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project (the project brand or its products).","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this entity is a configured competitor of the project.","example":false},"mentionCount":{"type":"number","description":"Total mention entries for this entity across all responses for this query (raw count, before dedup).","example":56},"visibility":{"type":"number","description":"Visibility percentage — how often this entity appears in AI responses for this query. Formula: (presentIn / totalResponses) × 100.","example":67},"shareOfVoice":{"type":"number","description":"Share of voice — this entity's portion of all entity mentions for this query. Formula: (mentionCount / total entity mentions) × 100. Values across all entities sum to 100%.","example":32.1},"avgRanking":{"type":"number","description":"Weighted average position rank for this entity in responses for this query. Lower values mean the entity appears earlier/higher in AI responses. 0 if no position data.","example":2.5},"sentimentScore":{"type":"number","description":"Average sentiment score for this entity across all mentions in this query. Scale: 0 (most negative) to 100 (most positive).","example":72.3},"sentiment":{"description":"Sentiment breakdown counts (positive / neutral / negative) for this entity in this query.","allOf":[{"$ref":"#/components/schemas/QueryDetailEntitySentiment"}]}},"required":["displayKey","displayName","isOwned","isPrimary","isCompetitor","mentionCount","visibility","shareOfVoice","avgRanking","sentimentScore","sentiment"]},"QueryDetailEntitySentiment":{"type":"object","properties":{"positive":{"type":"number","description":"Count of mentions with positive sentiment (score > 60).","example":35},"neutral":{"type":"number","description":"Count of mentions with neutral sentiment (score between 40 and 60).","example":15},"negative":{"type":"number","description":"Count of mentions with negative sentiment (score < 40).","example":6}},"required":["positive","neutral","negative"]},"QueryDetailResultItem":{"type":"object","properties":{"aiResponseId":{"type":"string","description":"AI response UUID.","example":"550e8400-e29b-41d4-a716-446655440000"},"initiatedAt":{"type":"string","description":"When the AI response was initiated (ISO 8601).","example":"2025-03-15T10:30:00.000Z"},"model":{"type":"string","description":"AI model used.","example":"gpt-4o"},"text":{"type":"string","description":"Full raw response text (markdown). Null if the response text was not stored.","example":"Here are the best CRM tools...","nullable":true},"noAnswerReason":{"type":"string","description":"Why the response has no text, when the provider knows it was deliberate: `declined` (Rufus refused), `customer_service` (Rufus sent the prompt to Amazon Customer Service), `no_ai_overview` / `no_ai_mode` (Google showed no AI answer). Null for answers and for older responses.","example":"customer_service","nullable":true},"hasSources":{"type":"boolean","description":"Whether this response includes source citations.","example":true},"hasShopping":{"type":"boolean","description":"Whether this response includes shopping products.","example":false},"hasAds":{"type":"boolean","description":"Whether this response rendered at least one sponsored ad.","example":false},"sources":{"description":"Source citations found in this response.","type":"array","items":{"$ref":"#/components/schemas/QueryResultSourceItem"}},"entities":{"description":"Entities mentioned in this response (after canonical dedup).","type":"array","items":{"$ref":"#/components/schemas/QueryResultEntityItem"}},"ads":{"description":"Sponsored ad cards rendered on this response, in render order. Empty when none.","type":"array","items":{"$ref":"#/components/schemas/QueryResultAdItem"}}},"required":["aiResponseId","initiatedAt","model","text","noAnswerReason","hasSources","hasShopping","hasAds","sources","entities","ads"]},"QueryDetailResultsResponse":{"type":"object","properties":{"results":{"description":"Paginated list of individual AI responses with their sources, entities, and sentiment.","type":"array","items":{"$ref":"#/components/schemas/QueryDetailResultItem"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["results","page"]},"QueryDetailSourcePoint":{"type":"object","properties":{"domain":{"type":"string","description":"Source domain name.","example":"reddit.com"},"resultCount":{"type":"number","description":"Number of distinct responses citing this domain.","example":12},"citationRate":{"type":"number","description":"Citation rate — resultCount / totalResponses × 100.","example":28.57},"pageCount":{"type":"number","description":"Total page-level citations from this domain.","example":18}},"required":["domain","resultCount","citationRate","pageCount"]},"QueryDetailSourcesByModelResponse":{"type":"object","properties":{"models":{"description":"Per-model source breakdown. Each entry contains the model name, run count, and top 5 cited domains.","type":"array","items":{"$ref":"#/components/schemas/SourceByModelItem"}}},"required":["models"]},"QueryDetailSourcesResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total AI responses for this query.","example":42},"sources":{"description":"Source domains cited in responses for this query, ordered by resultCount descending.","type":"array","items":{"$ref":"#/components/schemas/QueryDetailSourcePoint"}}},"required":["totalResponses","sources"]},"QueryLocalesResponse":{"type":"object","properties":{"countries":{"description":"Unique country codes (ISO 3166-1 alpha-2, from the supported allowlist) used by queries in this project.","example":["US","FR","DE"],"type":"array","items":{"type":"string"}},"languages":{"description":"Unique language codes (BCP-47-style, from the supported allowlist) used by queries in this project.","example":["en","fr","de"],"type":"array","items":{"type":"string"}}},"required":["countries","languages"]},"QueryResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier (UUID) of the query.","example":"a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6","format":"uuid"},"project":{"type":"object","description":"The project this query belongs to","example":"a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"},"tags":{"type":"object","example":[1,2,3],"description":"The tags IDs this query belongs to"},"query":{"type":"string","description":"The search query text tracked for this entry.","example":"mentionlab"},"language":{"type":"string","description":"ISO 639-1 language code used to scope the query results.","example":"en"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code used to scope the query results.","example":"US"},"type":{"description":"The type of question the query asks. Null for queries that have not been classified.","nullable":true,"allOf":[{"$ref":"#/components/schemas/QueryType"}]},"recurrenceSetting":{"nullable":true,"description":"The recurrence setting this query is linked to, or null when the query does not recur.","type":"object","allOf":[{"$ref":"#/components/schemas/RecurrenceSettingRefDto"}]},"updatedAt":{"format":"date-time","type":"string","description":"Timestamp of the last time the query was updated.","example":"2023-08-22T10:00:00.000Z"}},"required":["id","project","tags","query","language","country","updatedAt"]},"QueryResultAdItem":{"type":"object","properties":{"adId":{"type":"string","description":"The ad row's UUID.","example":"550e8400-e29b-41d4-a716-446655440000"},"brand":{"type":"string","description":"Advertised brand (canonical entity name). Null for unbranded creatives (image cards may name no brand — never derived from the advertiser).","example":"Garmin","nullable":true},"advertiser":{"type":"string","description":"Who paid for the placement (often a retailer). Raw text.","example":"Best Buy"},"format":{"type":"string","description":"Card format (provider-defined open set, e.g. 'product_card_v2', 'image_card_v2').","example":"image_card_v2"},"title":{"type":"string","description":"Ad creative title.","example":"Fenix 8"},"body":{"type":"string","description":"Ad creative body text.","example":"The …"},"creativeUrl":{"type":"string","description":"Public CDN URL of the captured creative image (immutable, cacheable). Null when the creative is not captured (capture in flight, or the provider link was already dead) — render no image then.","example":"https://cdn-bzr.mentionlab.io/creatives/3f2a…","nullable":true},"targetUrl":{"type":"string","description":"Landing page URL (paid-attribution params intact).","example":"https://…"},"price":{"type":"string","description":"Price as shipped (numeric string). Null on image cards.","example":"109.95","nullable":true},"priceCurrency":{"type":"string","description":"Price currency code. Null when there is no price.","example":"USD","nullable":true},"priceStrikethrough":{"type":"string","description":"Strikethrough (was) price. Null when absent.","example":"159.95","nullable":true},"priceStrikethroughCurrency":{"type":"string","description":"Strikethrough price currency. Null when absent.","example":"USD","nullable":true},"starRating":{"type":"number","description":"Star rating on the card (fractional). Null when absent.","example":4.2,"nullable":true},"positionRank":{"type":"number","description":"1-based render position within the ad unit.","example":1}},"required":["adId","brand","advertiser","format","title","body","creativeUrl","targetUrl","price","priceCurrency","priceStrikethrough","priceStrikethroughCurrency","starRating","positionRank"]},"QueryResultEntityItem":{"type":"object","properties":{"displayKey":{"type":"string","description":"Canonical entity ID. When aliases are merged, all variants resolve to this single key.","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable entity name.","example":"Acme Corp"},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":true},"sentimentScore":{"type":"number","description":"Sentiment score for this entity in this specific response. Scale: 0 (most negative) to 100 (most positive). Null if no sentiment data.","example":72.3,"nullable":true},"positionRank":{"type":"number","description":"Best (lowest) position rank of this entity in the response, across merged aliases. Null when unranked. Only populated by GET /api/v1/job-executions/{id}.","example":2,"nullable":true}},"required":["displayKey","displayName","isPrimary","sentimentScore"]},"QueryResultSourceItem":{"type":"object","properties":{"domain":{"type":"string","description":"Root domain of the cited source (e.g. reddit.com).","example":"reddit.com"},"url":{"type":"string","description":"Full URL of the cited page, if available.","example":"https://reddit.com/r/crm/..."}},"required":["domain"]},"QueryResultsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"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}}},"QueryStatsPoint":{"type":"object","properties":{"queryId":{"type":"string","description":"Query ID (UUID).","example":"550e8400-e29b-41d4-a716-446655440000"},"queryText":{"type":"string","description":"The query/prompt text that was sent to the AI model.","example":"best CRM software"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code for the query locale.","example":"US"},"language":{"type":"string","description":"ISO 639-1 language code for the query locale.","example":"en"},"type":{"description":"The type of question the query asks. Null for queries that have not been classified.","nullable":true,"allOf":[{"$ref":"#/components/schemas/QueryType"}]},"resultCount":{"type":"number","description":"Total number of AI responses for this query in the filtered scope (denominator for visibilityPct and sourcePresencePct).","example":42},"visibilityPct":{"type":"number","description":"Project brand visibility — percentage of this query's AI responses that mention the project brand entities. Formula: (brand mention count / resultCount) × 100.","example":65.5},"avgSentiment":{"type":"number","description":"Average sentiment score of the project brand mentions for this query. Scale: 0 (most negative) to 100 (most positive). Null when the brand was not mentioned in any response for this query.","example":72.3,"nullable":true},"avgRanking":{"type":"number","description":"Average position rank of the project brand mentions for this query. Lower values mean the brand tends to appear higher/earlier in responses. Null when the brand was not mentioned in any response for this query.","example":3.2,"nullable":true},"sourcePresencePct":{"type":"number","description":"Source presence — percentage of this query's AI responses that contain at least one source citation. Formula: (responses with sources / resultCount) × 100.","example":88.1},"shoppingPresencePct":{"type":"number","description":"Shopping presence — percentage of this query's AI responses that contain at least one shopping result. Formula: (responses with shopping / resultCount) × 100.","example":24},"adsPresencePct":{"type":"number","description":"Ads presence — percentage of this query's AI responses that rendered at least one sponsored ad. Formula: (responses with ads / resultCount) × 100.","example":15},"tagIds":{"description":"IDs of the tags associated with this query.","example":["1","3"],"type":"array","items":{"type":"string"}}},"required":["queryId","queryText","country","language","type","resultCount","visibilityPct","avgSentiment","avgRanking","sourcePresencePct","shoppingPresencePct","adsPresencePct"]},"QueryType":{"type":"string","enum":["comparative","informative","perception"],"description":"The type of question the query asks: \"comparative\" (compares options), \"informative\" (seeks facts or how-to information) or \"perception\" (probes opinions about a brand)."},"RecomputeRelationshipsResultResponse":{"type":"object","properties":{"added":{"type":"number","description":"Number of relationship rows added","example":4},"removed":{"type":"number","description":"Number of stale relationship rows removed","example":1},"total":{"type":"number","description":"Total relationship rows after recompute","example":7}},"required":["added","removed","total"]},"RecurrenceSettingRefDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the recurrence setting","example":"018f3a2b-7c4d-7e1a-9b2c-3d4e5f6a7b8c"},"name":{"type":"string","description":"Display name of the recurrence setting","example":"Daily core queries"}},"required":["id","name"]},"ResponseTextDto":{"type":"object","properties":{"aiResponseId":{"type":"string","description":"AI response id.","example":"550e8400-e29b-41d4-a716-446655440000"}},"required":["aiResponseId"]},"ResponseTextResponse":{"type":"object","properties":{"aiResponseId":{"type":"string"},"initiatedAt":{"type":"string","description":"When the response was generated (ISO 8601)."},"model":{"type":"string","nullable":true},"queryId":{"type":"string","nullable":true},"queryText":{"type":"string","nullable":true,"description":"The query prompt text."},"text":{"type":"string","nullable":true,"description":"Full AI response text."}},"required":["aiResponseId","initiatedAt","model","queryId","queryText","text"]},"RunPendingThemeAnalysisDto":{"type":"object","properties":{"force":{"type":"boolean","description":"Also re-enqueue jobs that were already handed off (resets their marker).","example":false}}},"RunPendingThemeAnalysisResponse":{"type":"object","properties":{"enqueued":{"type":"number","description":"Number of jobs enqueued for theme analysis.","example":5},"remaining":{"type":"number","description":"Jobs still pending after this batch (each call processes up to 200). Call again until 0.","example":0}},"required":["enqueued","remaining"]},"SentimentByEntityDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"entityIds":{"description":"Scope to specific entity IDs. If omitted, returns all non-blacklisted entities.","example":["550e8400-e29b-41d4-a716-446655440000","f47ac10b-58cc-4372-a567-0e02b2c3d479"],"type":"array","items":{"type":"string"}}}},"SentimentByEntityPoint":{"type":"object","properties":{"displayKey":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Entity display name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether the entity is owned by the project.","example":true},"isPrimary":{"type":"boolean","description":"Whether this is the primary project entity.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this is a competitor entity.","example":false},"sentimentScore":{"type":"number","description":"Average sentiment score (0–100).","example":72.3},"positive":{"type":"number","description":"Count of positive-sentiment mentions.","example":52},"neutral":{"type":"number","description":"Count of neutral-sentiment mentions.","example":18},"negative":{"type":"number","description":"Count of negative-sentiment mentions.","example":10},"mentionCount":{"type":"number","description":"AI responses that mention the entity (total mentions when grouped).","example":80}},"required":["displayKey","displayName","isOwned","isPrimary","isCompetitor","sentimentScore","positive","neutral","negative","mentionCount"]},"SentimentOverviewDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityIds":{"description":"Entity IDs to compute sentiment for. Defaults to project brand (primary non-blacklisted).","example":["3f8b1c2a-9d4e-4f6a-8b1c-2a9d4e4f6a8b"],"type":"array","items":{"type":"string"}}}},"SentimentOverviewResponse":{"type":"object","properties":{"sentimentScore":{"type":"number","description":"Average sentiment score (0–100). 0 = most negative, 100 = most positive.","example":72.3},"sentimentLabel":{"type":"string","description":"Derived sentiment label based on score: positive (>= 60), neutral (40–59), negative (< 40).","example":"positive"},"mentionCount":{"type":"number","description":"Total mention count included in the aggregation.","example":245},"positive":{"type":"number","description":"Count of mentions with positive sentiment.","example":165},"neutral":{"type":"number","description":"Count of mentions with neutral sentiment.","example":52},"negative":{"type":"number","description":"Count of mentions with negative sentiment.","example":28}},"required":["sentimentScore","sentimentLabel","mentionCount","positive","neutral","negative"]},"SentimentTimeseriesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"bucketSize":{"type":"string","description":"Time bucket granularity","enum":["day","week","month"],"example":"day"},"entityIds":{"description":"Entity IDs to compute sentiment for. Defaults to project brand (primary non-blacklisted).","example":["550e8400-e29b-41d4-a716-446655440000","550e8400-e29b-41d4-a716-446655440001"],"type":"array","items":{"type":"string"}}},"required":["bucketSize"]},"SentimentTimeseriesPoint":{"type":"object","properties":{"bucket":{"type":"string","description":"Start of the time bucket (ISO 8601).","example":"2025-01-01T00:00:00.000Z"},"sentimentScore":{"type":"number","description":"Average sentiment score for this bucket (0–100).","example":68.5},"positive":{"type":"number","description":"Count of positive-sentiment mentions in this bucket.","example":42},"neutral":{"type":"number","description":"Count of neutral-sentiment mentions in this bucket.","example":18},"negative":{"type":"number","description":"Count of negative-sentiment mentions in this bucket.","example":8},"presentIn":{"type":"number","description":"Distinct AI responses mentioning the brand in this bucket.","example":66},"mentionCount":{"type":"number","description":"Deprecated, use presentIn instead. Removed in a later release.","deprecated":true,"example":66}},"required":["bucket","sentimentScore","positive","neutral","negative","presentIn","mentionCount"]},"ShareOfVoiceDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}}}},"ShareOfVoicePoint":{"type":"object","properties":{"displayKey":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable entity name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project (i.e. the project's own brand or product).","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":true},"mentionCount":{"type":"number","description":"Number of AI responses that mention this entity (after canonical deduplication). Used as the numerator for shareOfVoice.","example":42},"shareOfVoice":{"type":"number","description":"Share of voice — this entity's portion of all entity mentions. Formula: (mentionCount / totalMentions) × 100. Values across all entities sum to 100%. Note: a single AI response mentioning 3 entities contributes to all 3, so totalMentions may exceed the number of AI responses.","example":28}},"required":["displayKey","displayName","isOwned","isPrimary","mentionCount","shareOfVoice"]},"ShareOfVoiceResponse":{"type":"object","properties":{"totalMentions":{"type":"number","description":"Sum of mentionCount across all non-blacklisted canonical entities (denominator for shareOfVoice). Because one AI response can mention multiple entities, this may exceed the total number of AI responses.","example":150},"brands":{"description":"Per-entity share of voice, sorted by mentionCount descending. Includes all non-blacklisted canonical entities for the project.","type":"array","items":{"$ref":"#/components/schemas/ShareOfVoicePoint"}}},"required":["totalMentions","brands"]},"ShoppingAllBrandPoint":{"type":"object","properties":{"entityId":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"entityName":{"type":"string","description":"Entity display name.","example":"Apple"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project.","example":true},"isPrimary":{"type":"boolean","description":"Whether this is the primary project entity.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this is a competitor entity.","example":false},"productCount":{"type":"number","description":"Number of distinct products associated with this brand in shopping results.","example":15},"visibility":{"type":"number","description":"Visibility — percentage of shopping-containing AI responses that include this brand. Formula: (distinct responses with entity / totalShoppingResponses) × 100.","example":67},"topMerchants":{"description":"Top merchants selling this brand's products (up to 3).","type":"array","items":{"$ref":"#/components/schemas/MerchantItem"}},"avgRating":{"type":"number","description":"Average star rating across all products. Null if no rating data.","example":4.3,"nullable":true},"avgPrice":{"type":"number","description":"Average price across all products. Null if no price data.","example":29.99,"nullable":true},"mentionCount":{"type":"number","description":"Total shopping product rows for this brand (raw count).","example":156},"shareOfShelf":{"type":"number","description":"Share of shelf: this brand's product rows as a percentage of every shopping product row, unmatched rows included.","example":12.5},"shareOfVoice":{"type":"number","description":"Deprecated, use shareOfShelf instead (the same value). Removed in a later release.","deprecated":true,"example":12.5}},"required":["entityId","entityName","isOwned","isPrimary","isCompetitor","productCount","visibility","topMerchants","avgRating","avgPrice","mentionCount","shareOfShelf","shareOfVoice"]},"ShoppingAllBrandsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"entityIds":{"description":"Entity IDs to filter by specific brands (defaults to all non-blacklisted).","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}},"page":{"type":"number","description":"Page number (1-based).","default":1,"example":1},"pageSize":{"type":"number","description":"Items per page (max 200).","default":50,"example":50},"brandName":{"type":"string","description":"Case-insensitive substring match on brand name.","example":"nike"},"sort":{"description":"Sort order. Allowed fields: entityName, productCount, visibility, avgRating, avgPrice, mentionCount.","example":[{"field":"visibility","direction":"DESC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"ShoppingAllBrandsResponse":{"type":"object","properties":{"totalShoppingResponses":{"type":"number","description":"Total distinct AI responses with shopping products (denominator for visibility).","example":150},"brands":{"description":"All brands, sorted and paginated.","type":"array","items":{"$ref":"#/components/schemas/ShoppingAllBrandPoint"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["totalShoppingResponses","brands","page"]},"ShoppingAllMerchantsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"page":{"type":"number","description":"Page number (1-based).","default":1,"example":1},"pageSize":{"type":"number","description":"Items per page (max 200).","default":50,"example":50},"entityIds":{"description":"Entity IDs for brand-specific metrics (defaults to primary non-blacklisted).","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"type":"array","items":{"type":"string"}},"merchantName":{"type":"string","description":"Case-insensitive substring match on merchant name.","example":"amazon"},"sort":{"description":"Sort order. Allowed fields: merchantName, citationRate, citationShare, entityCitationShare, trueReach, mentionCount.","example":[{"field":"citationShare","direction":"DESC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"ShoppingAllMerchantsResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total AI responses in filtered scope (denominator for citationRate).","example":365},"totalMerchantCitations":{"type":"number","description":"Sum of mentionCount across all merchants (denominator for citationShare).","example":450},"totalBrandMentions":{"type":"number","description":"Sum of brand-matched mention counts across all merchants (denominator for entityCitationShare).","example":200},"merchants":{"description":"Merchant list, sorted and paginated.","type":"array","items":{"$ref":"#/components/schemas/ShoppingMerchantPoint"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["totalResponses","totalMerchantCitations","totalBrandMentions","merchants","page"]},"ShoppingAllProductPoint":{"type":"object","properties":{"productId":{"type":"string","description":"Canonical product ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"productName":{"type":"string","description":"Product display name.","example":"iPhone 16 Pro"},"brandEntityId":{"type":"string","description":"Brand entity ID.","example":"550e8400-e29b-41d4-a716-446655440001"},"brandName":{"type":"string","description":"Brand display name.","example":"Apple"},"isOwned":{"type":"boolean","description":"Whether the brand entity is owned."},"isPrimary":{"type":"boolean","description":"Whether the brand entity is primary."},"isCompetitor":{"type":"boolean","description":"Whether the brand entity is a competitor."},"visibility":{"type":"number","description":"Visibility — percentage of shopping-containing AI responses that include this product. Formula: (distinct responses with product / totalShoppingResponses) × 100.","example":34},"merchants":{"description":"Top merchants selling this product (up to 3).","type":"array","items":{"$ref":"#/components/schemas/MerchantItem"}},"avgPrice":{"type":"number","description":"Average price across all occurrences. Null if no price data.","example":999,"nullable":true},"avgRating":{"type":"number","description":"Average star rating. Null if no rating data.","example":4.5,"nullable":true},"mentionCount":{"type":"number","description":"Total shopping product rows for this product (raw count).","example":42},"imageUrl":{"type":"string","description":"Representative product image URL. Null when none is known.","example":"https://example.com/img/product-123.jpg","nullable":true}},"required":["productId","productName","brandEntityId","brandName","isOwned","isPrimary","isCompetitor","visibility","merchants","avgPrice","avgRating","mentionCount","imageUrl"]},"ShoppingAllProductsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"entityIds":{"description":"Entity IDs to filter products by brand (defaults to all non-blacklisted).","example":["8d3c2f1a-1b2c-4d5e-9f01-23456789abcd"],"type":"array","items":{"type":"string"}},"page":{"type":"number","description":"Page number (1-based).","default":1,"example":1},"pageSize":{"type":"number","description":"Items per page (max 200).","default":50,"example":50},"productName":{"type":"string","description":"Case-insensitive substring match on product name.","example":"wireless headphones"},"sort":{"description":"Sort order. Allowed fields: productName, brandName, visibility, avgPrice, avgRating, mentionCount.","example":[{"field":"visibility","direction":"DESC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"ShoppingAllProductsResponse":{"type":"object","properties":{"totalShoppingResponses":{"type":"number","description":"Total distinct AI responses with shopping products (denominator for visibility).","example":150},"unmappedUnknownCount":{"type":"number","description":"Shopping appearances assigned to a brand but not resolved to a specific product (the \"Unknown\" bucket), within the current filters.","example":12},"unmappedNotMatchedCount":{"type":"number","description":"Shopping appearances with neither a brand nor a product resolved (the \"Not matched\" bucket), within the current filters.","example":5},"products":{"description":"All products, sorted and paginated.","type":"array","items":{"$ref":"#/components/schemas/ShoppingAllProductPoint"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["totalShoppingResponses","unmappedUnknownCount","unmappedNotMatchedCount","products","page"]},"ShoppingItemMerchantUrl":{"type":"object","properties":{"url":{"type":"string","description":"Merchant product page URL.","example":"https://www.amazon.com/dp/B0CQXYZABC"},"merchantName":{"type":"string","description":"Merchant display name.","example":"Amazon"},"merchantDomain":{"type":"string","description":"Merchant domain (e.g. amazon.com). Null if not set.","example":"amazon.com"},"price":{"type":"number","description":"Merchant-specific price.","example":"999.99","nullable":true},"priceCurrency":{"type":"string","description":"Merchant-specific price currency.","example":"USD"},"merchantPosition":{"type":"number","description":"1-based rank of this merchant in ChatGPT's offer list for the product. Null if unknown.","example":1,"nullable":true},"aboveFold":{"type":"boolean","description":"Whether the merchant was shown by default (true) or hidden behind \"Show more offers\" (false). Null if unknown.","example":true,"nullable":true},"shippingPrice":{"type":"number","description":"Shipping cost in the offer's currency: 0 = free, > 0 = the cost, null = unknown.","example":7.9,"nullable":true},"availability":{"type":"boolean","description":"Whether the offer is in stock / available. Null if unknown.","example":true,"nullable":true},"details":{"type":"string","description":"Verbatim stock + delivery string shown for this offer (localized, unstructured), e.g. \"In stock online, Delivery €7.90\". Null if unknown.","example":"In stock online, Delivery €7.90","nullable":true}},"required":["url","merchantName","price","merchantPosition","aboveFold","shippingPrice","availability","details"]},"ShoppingItemResponse":{"type":"object","properties":{"id":{"type":"string","description":"Shopping product row ID.","format":"uuid","example":"d290f1ee-6c54-4b01-90e6-d701748f0851"},"initiatedAt":{"format":"date-time","type":"string","description":"Timestamp when the product was captured.","example":"2026-06-08T14:30:00.000Z"},"jobExecutionId":{"type":"string","description":"ID of the job execution (run) that produced this product.","format":"uuid","example":"b4f0c2a1-9d3e-4f5a-8c7b-1e2d3f4a5b6c"},"externalId":{"type":"string","description":"External ID from the source.","example":"B0CQXYZABC"},"rawName":{"type":"string","description":"Raw product name as extracted.","example":"Apple iPhone 15 Pro 256GB Natural Titanium"},"positionRank":{"type":"number","description":"Position rank in the shopping results.","example":1},"imageUrl":{"type":"string","description":"Product image URL.","example":"https://m.media-amazon.com/images/I/81dT7CUY6GL._AC_SL1500_.jpg"},"price":{"type":"number","description":"Product price.","example":"999.99","nullable":true},"priceCurrency":{"type":"string","description":"Product price currency.","example":"USD"},"starRating":{"type":"number","description":"Product star rating.","example":4.5,"nullable":true},"reviewCount":{"type":"number","description":"Number of product reviews.","example":1234,"nullable":true},"entityId":{"type":"string","description":"Resolved brand entity ID.","format":"uuid","example":"f1c2d3e4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"},"entityName":{"type":"string","description":"Resolved brand entity name.","example":"Apple"},"productId":{"type":"string","description":"Resolved product ID.","format":"uuid","example":"a7b8c9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d"},"productName":{"type":"string","description":"Resolved product name.","example":"iPhone 16 Pro"},"merchantUrls":{"description":"Merchant URLs where this product is available.","example":[{"url":"https://www.amazon.com/dp/B0CQXYZABC","merchantName":"Amazon","merchantDomain":"amazon.com","price":999.99,"priceCurrency":"USD","merchantPosition":1,"aboveFold":true,"shippingPrice":7.9,"availability":true,"details":"In stock online, Delivery $7.90"}],"type":"array","items":{"$ref":"#/components/schemas/ShoppingItemMerchantUrl"}}},"required":["id","initiatedAt","jobExecutionId","rawName","positionRank","price","reviewCount","merchantUrls"]},"ShoppingMerchantPoint":{"type":"object","properties":{"merchantId":{"type":"string","description":"Merchant UUID.","example":"550e8400-e29b-41d4-a716-446655440000"},"merchantName":{"type":"string","description":"Merchant display name.","example":"Amazon"},"domain":{"type":"string","description":"Merchant domain if known.","example":"amazon.com","nullable":true},"mentionCount":{"type":"number","description":"Number of distinct products this merchant is cited for.","example":45},"citationRate":{"type":"number","description":"Citation rate — how often this merchant appears across all AI responses. Formula: (distinct AI responses citing this merchant / totalResponses) × 100.","example":28},"citationShare":{"type":"number","description":"Citation share — this merchant's portion of all merchant citations. Formula: (mentionCount / totalMerchantCitations) × 100.","example":15},"entityCitationShare":{"type":"number","description":"Entity citation share — this merchant's portion of all brand-matched merchant rows. Formula: (brandMentionCount / totalBrandMentions) × 100. Values across all merchants sum to 100%. Shows which merchants drive brand presence.","example":22.5},"trueReach":{"type":"number","description":"True reach — percentage of this merchant's product rows that mention the brand. Formula: (brandMentionCount / mentionCount) × 100. A per-merchant quality indicator of brand alignment.","example":40},"aboveFoldShare":{"type":"number","description":"Above-fold share — percentage of this merchant's offer appearances shown by default (not hidden behind \"Show more offers\"). Formula: (appearances above the fold / appearances with a known fold flag) × 100. Null when no appearance has a known fold flag.","example":62.5,"nullable":true},"avgPosition":{"type":"number","description":"Average 1-based offer rank for this merchant across appearances (lower is more prominent). Null when no appearance has a known position.","example":2.4,"nullable":true},"freeShippingShare":{"type":"number","description":"Free-shipping share — percentage of this merchant's offers that ship free. Formula: (offers with shippingPrice = 0 / offers with a known shipping price) × 100. Null when no offer has a known shipping price.","example":40,"nullable":true},"avgShippingPrice":{"type":"number","description":"Average shipping cost across this merchant's offers with a known price (free offers count as 0). Currency-naive — mixes currencies if the project spans several, same as price fields. Null when no offer has a known shipping price.","example":4.95,"nullable":true},"inStockShare":{"type":"number","description":"In-stock share — percentage of this merchant's offers marked available. Formula: (offers available / offers with a known availability flag) × 100. Null when no offer has a known availability flag.","example":95,"nullable":true}},"required":["merchantId","merchantName","domain","mentionCount","citationRate","citationShare","entityCitationShare","trueReach","aboveFoldShare","avgPosition","freeShippingShare","avgShippingPrice","inStockShare"]},"ShoppingMerchantProductPoint":{"type":"object","properties":{"productId":{"type":"string","description":"Product UUID (canonical resolved).","example":"550e8400-e29b-41d4-a716-446655440000"},"productName":{"type":"string","description":"Product display name.","example":"iPhone 16 Pro"},"brandName":{"type":"string","description":"Brand display name.","example":"Apple"},"share":{"type":"number","description":"Share — this product's portion of all products for this merchant. Formula: (mentionCount / totalMentionsForMerchant) × 100.","example":15},"minPrice":{"type":"number","description":"Minimum price observed at this merchant. Null if no price data.","example":799,"nullable":true},"maxPrice":{"type":"number","description":"Maximum price observed at this merchant. Null if no price data.","example":1199,"nullable":true},"avgPrice":{"type":"number","description":"Average price at this merchant. Null if no price data.","example":999,"nullable":true},"avgRating":{"type":"number","description":"Average star rating across occurrences. Null if no rating data.","example":4.5,"nullable":true},"reviewCount":{"type":"number","description":"Total review count across occurrences. Null if no review data.","example":2300,"nullable":true},"avgPosition":{"type":"number","description":"Average position rank in shopping results. Lower = earlier/higher in the list.","example":2.3},"productUrl":{"type":"string","description":"Representative product page URL on this merchant. Picks the latest primary URL (or latest non-primary fallback) within the request scope. Null when no URL has ever been captured for this (merchant, product).","example":"https://www.amazon.com/dp/B0CQXYZABC","nullable":true}},"required":["productId","productName","brandName","share","minPrice","maxPrice","avgPrice","avgRating","reviewCount","avgPosition","productUrl"]},"ShoppingMerchantProductsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"page":{"type":"number","description":"Page number (1-based).","default":1,"example":1},"pageSize":{"type":"number","description":"Items per page (max 200).","default":50,"example":50}}},"ShoppingMerchantProductsResponse":{"type":"object","properties":{"products":{"description":"Products for this merchant, paginated.","type":"array","items":{"$ref":"#/components/schemas/ShoppingMerchantProductPoint"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["products","page"]},"ShoppingOverviewDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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}}},"ShoppingOverviewResponse":{"type":"object","properties":{"shoppingCoverage":{"type":"number","description":"Shopping coverage — percentage of all AI responses that contain shopping/product content. Formula: (responses with has_shopping=true / totalResponses) × 100.","example":34.5,"nullable":true},"identifiedBrands":{"type":"number","description":"Number of unique brands (entities) identified in shopping results. Only counts products where entity resolution has completed.","example":12},"identifiedProducts":{"type":"number","description":"Number of unique products identified in shopping results. Only counts products where product resolution has completed.","example":87},"identifiedMerchants":{"type":"number","description":"Number of unique merchants/retailers found in shopping results.","example":8}},"required":["shoppingCoverage","identifiedBrands","identifiedProducts","identifiedMerchants"]},"ShoppingVisibilityTimeseriesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"bucketSize":{"type":"string","description":"Time bucket granularity.","enum":["day","week","month"],"example":"day"},"entityIds":{"description":"Entity IDs to track (defaults to primary non-blacklisted entities).","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}}},"required":["bucketSize"]},"ShoppingVisibilityTimeseriesEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"entityName":{"type":"string","description":"Entity display name.","example":"Acme Corp"}},"required":["entityId","entityName"]},"ShoppingVisibilityTimeseriesPoint":{"type":"object","properties":{"bucket":{"type":"string","description":"Start of the time bucket (ISO 8601).","example":"2025-03-01T00:00:00.000Z"},"entityId":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"entityName":{"type":"string","description":"Entity display name.","example":"Acme Corp"},"visibility":{"type":"number","description":"Visibility percentage — how often this entity appears in shopping results in this bucket. Formula: (distinct AI responses with this entity in shopping / total shopping responses in bucket) × 100.","example":45}},"required":["bucket","entityId","entityName","visibility"]},"ShoppingVisibilityTimeseriesResponse":{"type":"object","properties":{"entities":{"description":"List of tracked entities.","type":"array","items":{"$ref":"#/components/schemas/ShoppingVisibilityTimeseriesEntity"}},"points":{"description":"Timeseries data points, one per (bucket, entity) pair.","type":"array","items":{"$ref":"#/components/schemas/ShoppingVisibilityTimeseriesPoint"}}},"required":["entities","points"]},"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"]},"SourceAllDomainsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"tlds":{"description":"Restrict to source domains whose ICANN public suffix is one of these values. Matched exactly against the full suffix (e.g. \"co.uk\", not \"uk\").","example":["be","co.uk"],"type":"array","items":{"type":"string"}},"entityIds":{"description":"Entity IDs to compute brand metrics for (defaults to primary non-blacklisted)","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}},"limit":{"type":"number","description":"Max domains to return (omit for all)","example":50},"page":{"type":"number","description":"Page number (1-based).","default":1,"example":1},"pageSize":{"type":"number","description":"Items per page (max 200).","default":50,"example":50},"categorySlugs":{"description":"Filter to domains whose resolved source-type category matches one of these slugs. Pass 'other' to match uncategorised domains.","example":["news_media","community_ugc"],"type":"array","items":{"type":"string"}},"search":{"type":"string","description":"Case-insensitive substring filter on the domain name (e.g. \"reddit\" matches reddit.com).","example":"reddit"},"sort":{"description":"Sorting criteria applied to the returned domains. Each entry pairs a sortable field (e.g. domain, resultCount, citationRate, citationShare, pageCount, brandPageCount, entityCitationShare, presence, brandResultCount, trueReach) with a sort direction.","example":[{"field":"citationShare","direction":"desc"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"SourceAllDomainsPoint":{"type":"object","properties":{"sourceDomainId":{"type":"string","description":"Source domain UUID. Use as sourceDomainId for domain-entities and domain-urls endpoints.","example":"01234567-89ab-cdef-0123-456789abcdef"},"domain":{"type":"string","description":"Root domain name (e.g. reddit.com).","example":"reddit.com"},"categorySlug":{"type":"string","description":"Source-type category slug for this domain. Resolves the project-scoped override first, then the global default; null when uncategorised.","nullable":true,"example":"news_media"},"categoryLabel":{"type":"string","description":"Human-readable label for categorySlug; null when uncategorised.","nullable":true,"example":"News & Media"},"resultCount":{"type":"number","description":"Number of distinct AI responses that cited at least one page from this domain. A single response citing 3 reddit.com pages counts as 1.","example":102},"citationRate":{"type":"number","description":"Citation rate — how often this domain appears across ALL AI responses. Formula: (resultCount / totalResponses) × 100.","example":28},"citationShare":{"type":"number","description":"Citation share — this domain's portion of all source citations. Formula: (resultCount / totalCitations) × 100. Values across all domains sum to 100%.","example":14.3},"pageCount":{"type":"number","description":"Total number of unique page URLs cited from this domain. The same URL cited by multiple AI responses is counted once.","example":178},"brandPageCount":{"type":"number","description":"Number of unique page URLs from this domain where the selected entities (brand) were mentioned at least once. Subset of pageCount.","example":45},"entityCitationShare":{"type":"number","description":"Entity citation share — this domain's portion of ALL brand-mentioned pages across all domains. Formula: (brandPageCount / totalBrandPages) × 100. Values across all domains sum to 100%. Shows which sources drive brand presence.","example":22.5},"presence":{"type":"number","description":"Presence — the percentage of this domain's cited pages that also mention the brand. Formula: (brandPageCount / pageCount) × 100. A per-domain quality indicator of brand alignment.","example":25.3},"brandResultCount":{"type":"number","description":"Number of distinct AI responses where this domain cited at least one brand-mentioned page. Subset of resultCount — only responses where the domain serves as a brand citation source.","example":38},"trueReach":{"type":"number","description":"True Reach — of this domain's total citations, what percentage reference the brand. Formula: (brandCitationCount / totalCitationCount) × 100.","example":10.4},"pendingCitations":{"type":"number","description":"Number of cited pages from this domain whose source analysis is still in progress. Analysis-derived metrics (brand mentions, True Reach) converge as this reaches 0.","example":3}},"required":["sourceDomainId","domain","categorySlug","categoryLabel","resultCount","citationRate","citationShare","pageCount","brandPageCount","entityCitationShare","presence","brandResultCount","trueReach","pendingCitations"]},"SourceAllDomainsResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope. Used as the denominator for citationRate.","example":365},"totalCitations":{"type":"number","description":"Sum of resultCount across all source domains. Used as the denominator for citationShare. Note: this can exceed totalResponses because one response may cite multiple domains.","example":712},"totalBrandPages":{"type":"number","description":"Sum of brandPageCount across all source domains. Used as the denominator for entityCitationShare.","example":200},"sources":{"description":"Per-domain statistics with all citation and brand reach metrics, ordered by resultCount descending (unless sorted).","type":"array","items":{"$ref":"#/components/schemas/SourceAllDomainsPoint"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["totalResponses","totalCitations","totalBrandPages","sources","page"]},"SourceByModelItem":{"type":"object","properties":{"model":{"type":"string","description":"AI model name.","example":"gpt-4o"},"runCount":{"type":"number","description":"Total number of AI responses from this model for the query (denominator for citationRate).","example":18},"sources":{"description":"Top 5 source domains cited by this model, ordered by resultCount descending.","type":"array","items":{"$ref":"#/components/schemas/SourceByModelSourceItem"}}},"required":["model","runCount","sources"]},"SourceByModelSourceItem":{"type":"object","properties":{"domain":{"type":"string","description":"Root domain name (e.g. reddit.com).","example":"reddit.com"},"resultCount":{"type":"number","description":"Number of distinct AI responses from this model that cited at least one page from this domain.","example":6},"citationRate":{"type":"number","description":"Citation rate within this model — how often this domain appears across this model's responses for the query. Formula: (resultCount / runCount) × 100.","example":33.33}},"required":["domain","resultCount","citationRate"]},"SourceCategoryResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"news"},"label":{"type":"string","example":"News"}},"required":["id","slug","label"]},"SourceDomainCategorizationStatus":{"type":"string","enum":["pending","done","failed"],"description":"Source-categorisation lifecycle state of this domain: `done` = categorised, `pending`/`failed` = still in the categorisation pipeline, null = never queued. Use to spot sources missing a category before extracting."},"SourceDomainEntitiesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"sourceDomainId":{"type":"string","description":"Source domain ID to drill down into.","example":"0199c3a4-7f2b-7c31-9d55-2b0e4f6a8c11"}},"required":["sourceDomainId"]},"SourceDomainEntitiesResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope.","example":720},"domainTotalCitationCount":{"type":"number","description":"Total citation rows from this domain (one per aiResponse × url pair). Denominator for trueReach.","example":420},"domainPageCount":{"type":"number","description":"Total number of distinct page URLs cited from this domain. Denominator for presence.","example":178},"entities":{"description":"Entities found on pages from this domain, ordered by brandResultCount descending. Only entities actually detected on at least one page are included.","type":"array","items":{"$ref":"#/components/schemas/SourceDomainEntityPoint"}}},"required":["totalResponses","domainTotalCitationCount","domainPageCount","entities"]},"SourceDomainEntityPoint":{"type":"object","properties":{"entityId":{"type":"string","description":"Canonical entity ID.","example":"01234567-89ab-cdef-0123-456789abcdef"},"entityName":{"type":"string","description":"Entity display name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project owner.","example":true},"isPrimary":{"type":"boolean","description":"Whether this is the primary entity for the project.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this entity is marked as a competitor.","example":false},"brandResultCount":{"type":"number","description":"Number of distinct AI responses where this domain cited a page that mentions this entity. Same concept as brandResultCount in all-domains, but scoped to one entity.","example":38},"brandCitationCount":{"type":"number","description":"Number of citation rows from this domain where this entity was found. One citation row = one (aiResponse × url) pair. Numerator for trueReach.","example":42},"trueReach":{"type":"number","description":"True Reach — of this domain's total citations, what percentage reference this entity. Formula: (brandCitationCount / domainTotalCitationCount) × 100.","example":10.4},"brandPageCount":{"type":"number","description":"Number of distinct page URLs from this domain where this entity was found. Numerator for presence.","example":45},"presence":{"type":"number","description":"Presence — what percentage of this domain's distinct cited pages mention this entity. Formula: (brandPageCount / domainPageCount) × 100.","example":25.3}},"required":["entityId","entityName","isOwned","isPrimary","isCompetitor","brandResultCount","brandCitationCount","trueReach","brandPageCount","presence"]},"SourceDomainReachDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"tlds":{"description":"Restrict to source domains whose ICANN public suffix is one of these values. Matched exactly against the full suffix (e.g. \"co.uk\", not \"uk\").","example":["be","co.uk"],"type":"array","items":{"type":"string"}},"entityIds":{"description":"Entity IDs to compute true reach for (defaults to primary non-blacklisted)","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}},"size":{"type":"number","description":"Max domains to return (default 15, max 50)","default":15,"example":15}}},"SourceDomainReachPoint":{"type":"object","properties":{"domain":{"type":"string","description":"Root domain name (e.g. reddit.com)","example":"reddit.com"},"resultCount":{"type":"number","description":"Number of distinct AI responses that cited at least one page from this domain. A single response citing 3 reddit.com pages counts as 1.","example":42},"citationRate":{"type":"number","description":"Citation rate — how often this domain appears across all AI responses. Formula: (resultCount / totalResponses) × 100. Example: 28% means 28 out of every 100 AI responses reference this domain.","example":28},"pageCount":{"type":"number","description":"Total number of individual page citations from this domain. One AI response may cite multiple pages from the same domain, each counted separately.","example":67},"brandPageCount":{"type":"number","description":"Number of cited pages from this domain where the selected entities (brand) were mentioned. Subset of pageCount — only pages that also reference the brand.","example":30},"trueReach":{"type":"number","description":"True Reach — of this domain's total citations, what percentage reference the brand. Formula: (brandCitationCount / totalCitationCount) × 100. Example: 44.78% means ~45% of citation rows from this domain involve the brand.","example":44.78}},"required":["domain","resultCount","citationRate","pageCount","brandPageCount","trueReach"]},"SourceDomainReachResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope. Used as the denominator for citationRate.","example":150},"sources":{"description":"Per-domain citation and reach statistics, ordered by resultCount descending","type":"array","items":{"$ref":"#/components/schemas/SourceDomainReachPoint"}}},"required":["totalResponses","sources"]},"SourceDomainUrlEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"Canonical entity ID.","example":"01234567-89ab-cdef-0123-456789abcdef"},"entityName":{"type":"string","description":"Entity display name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project owner.","example":true},"isPrimary":{"type":"boolean","description":"Whether this is the primary entity for the project.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this entity is marked as a competitor.","example":false}},"required":["entityId","entityName","isOwned","isPrimary","isCompetitor"]},"SourceDomainUrlPoint":{"type":"object","properties":{"url":{"type":"string","description":"Full URL of the cited page.","example":"https://www.reddit.com/r/technology/comments/abc123/title"},"title":{"type":"string","description":"Page title (may be null if not captured).","example":"Best tools for project management - Reddit","nullable":true},"citationCount":{"type":"number","description":"Number of distinct AI responses that cited this specific URL. Each AI response is counted once regardless of how many times it references the URL.","example":15},"citationShare":{"type":"number","description":"This URL's share of all citations globally (across all domains). Formula: (citationCount / globalTotalCitations) × 100. Consistent with citationShare in all-domains (same denominator concept).","example":2.1},"brandCitationCount":{"type":"number","description":"Number of AI responses where this URL was cited AND the brand entity was found on the page. Subset of citationCount.","example":6},"brandCitationShare":{"type":"number","description":"This URL's share of all brand citations globally. Formula: (brandCitationCount / globalTotalBrandCitations) × 100. Shows how much of the global brand citation volume flows through this specific page.","example":3.4},"successCount":{"type":"number","description":"Number of successful page scrapes for this URL.","example":12},"failureCount":{"type":"number","description":"Number of failed page scrapes for this URL.","example":3},"entities":{"description":"Entities found on this URL (canonical-deduplicated, excludes blacklisted). Shows which brands/entities are associated with this specific page.","type":"array","items":{"$ref":"#/components/schemas/SourceDomainUrlEntity"}}},"required":["url","title","citationCount","citationShare","brandCitationCount","brandCitationShare","successCount","failureCount","entities"]},"SourceDomainUrlsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"page":{"type":"number","description":"Page number (1-based).","default":1,"example":1},"pageSize":{"type":"number","description":"Items per page (max 200).","default":50,"example":50},"sourceDomainId":{"type":"string","description":"Source domain ID to drill down into.","example":"0199c3a4-7f2b-7c31-9d55-2b0e4f6a8c11"},"entityIds":{"description":"Entity IDs to compute brand metrics for (defaults to primary non-blacklisted).","example":["0199c3a4-7f2b-7c31-9d55-2b0e4f6a8c11"],"type":"array","items":{"type":"string"}},"sort":{"description":"Sorting instructions for the result set. Allowed fields are url, citationCount, citationShare, brandCitationCount, brandCitationShare, successCount and failureCount.","example":[{"field":"citationCount","direction":"desc"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}},"required":["sourceDomainId"]},"SourceDomainUrlsResponse":{"type":"object","properties":{"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope.","example":720},"globalTotalCitations":{"type":"number","description":"Sum of per-domain citation counts across ALL domains. Denominator for citationShare. Consistent with totalCitations in all-domains.","example":712},"globalTotalBrandCitations":{"type":"number","description":"Sum of per-domain brand citation counts across ALL domains. Denominator for brandCitationShare.","example":200},"urls":{"description":"Per-URL statistics ordered by citationCount descending (unless sorted).","type":"array","items":{"$ref":"#/components/schemas/SourceDomainUrlPoint"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["totalResponses","globalTotalCitations","globalTotalBrandCitations","urls","page"]},"SourceTimeseriesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"bucketSize":{"type":"string","description":"Time bucket granularity","enum":["day","week","month"],"example":"day"},"tlds":{"description":"Restrict to source domains whose ICANN public suffix is one of these values. Matched exactly against the full suffix (e.g. \"co.uk\", not \"uk\").","example":["be","co.uk"],"type":"array","items":{"type":"string"}}},"required":["bucketSize"]},"SourceTimeseriesPoint":{"type":"object","properties":{"bucket":{"type":"string","description":"Start of the time bucket (ISO 8601). Granularity depends on the requested bucketSize (day/week/month).","example":"2026-03-01T00:00:00.000Z"},"domain":{"type":"string","description":"Root domain name (e.g. reddit.com)","example":"reddit.com"},"resultCount":{"type":"number","description":"Number of distinct AI responses that cited this domain within this bucket.","example":12},"citationShare":{"type":"number","description":"Citation share within this time bucket — this domain's portion of all citations in the bucket. Formula: (resultCount / bucket total citations) × 100. Per-bucket shares across the returned 5 domains will sum to ≤ 100% (less than 100 because other domains outside the top 5 also have citations).","example":22.5},"citationRate":{"type":"number","description":"Citation rate within this time bucket — percentage of AI responses in the bucket that cite this domain. Formula: (resultCount / bucket total responses) × 100. Unlike citationShare (which divides by citations), citation rate measures reach across responses.","example":8}},"required":["bucket","domain","resultCount","citationShare","citationRate"]},"SourceTimeseriesResponse":{"type":"object","properties":{"domains":{"description":"The top 5 domain names ordered by total citations across the full date range. Every bucket in `points` will contain an entry for each of these 5 domains (0 if absent).","example":["reddit.com","wikipedia.org","youtube.com","github.com","stackoverflow.com"],"type":"array","items":{"type":"string"}},"points":{"description":"Flat array of data points — one entry per (bucket × domain) combination. Ordered by bucket ascending, then by domain rank descending within each bucket.","type":"array","items":{"$ref":"#/components/schemas/SourceTimeseriesPoint"}}},"required":["domains","points"]},"SourceTldBreakdownDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"size":{"type":"number","description":"Max TLDs to return (default 50, max 200)","default":50,"example":50}}},"SourceTldBreakdownPoint":{"type":"object","properties":{"tld":{"type":"string","description":"ICANN public suffix of the cited domain (e.g. \"be\", \"co.uk\", \"com\"). Null when the domain has no recognised public suffix.","example":"be","nullable":true},"resultCount":{"type":"number","description":"Distinct AI responses that cited a domain with this TLD.","example":142},"domainCount":{"type":"number","description":"Distinct domains with this TLD that received a citation.","example":23},"pageCount":{"type":"number","description":"Total page citations from domains with this TLD.","example":318},"citationShare":{"type":"number","description":"This TLD's share of all source citations (%). Sums to 100% across returned TLDs.","example":18.5},"citationRate":{"type":"number","description":"Percentage of all AI responses that cite this TLD.","example":9.4}},"required":["tld","resultCount","domainCount","pageCount","citationShare","citationRate"]},"SourceTldBreakdownResponse":{"type":"object","properties":{"totalCitations":{"type":"number","description":"Total source citations across all returned TLDs.","example":769},"totalResponses":{"type":"number","description":"AI responses matching the request filters.","example":1500},"tlds":{"description":"Breakdown of citations by ICANN public suffix.","type":"array","items":{"$ref":"#/components/schemas/SourceTldBreakdownPoint"}}},"required":["totalCitations","totalResponses","tlds"]},"SourceTopicRunResponse":{"type":"object","properties":{"id":{"type":"string","description":"Run UUID.","example":"019dd32e-b19e-7956-88f6-4b9a877f3697"},"status":{"description":"Lifecycle status of the run.","example":"running","allOf":[{"$ref":"#/components/schemas/SourceTopicRunStatus"}]},"totalSources":{"type":"number","description":"Total sources (jobs) enqueued for this run.","example":100},"processed":{"type":"number","description":"Sources processed so far (vectorized + skippedNoMeta + skippedPreMeta + failed). Use processed / totalSources for a progress bar.","example":64},"vectorized":{"type":"number","description":"Sources whose metadata was embedded + stored.","example":41},"skippedNoMeta":{"type":"number","description":"Sources skipped because no metadata sidecar was cached.","example":18},"skippedPreMeta":{"type":"number","description":"Sources skipped because the snapshot predates metadata caching.","example":4},"failed":{"type":"number","description":"Sources whose job failed terminally (retries exhausted).","example":1},"params":{"type":"object","description":"Snapshot of the filters that produced this run.","nullable":true,"example":{"startDate":"2026-06-01","countries":["US"]}},"createdAt":{"type":"string","description":"When the run was created.","format":"date-time","example":"2026-06-25T13:35:29.000Z"},"updatedAt":{"type":"string","description":"When the run last changed.","format":"date-time","example":"2026-06-25T13:38:02.000Z"},"completedAt":{"type":"string","description":"When the run finished (null while still running).","format":"date-time","nullable":true,"example":"2026-06-25T13:40:11.000Z"},"topicsStatus":{"description":"Topic-clustering lifecycle, independent of embedding `status`. `pending` while embedding; `clustering` once the topic job runs; `ready` when topics are available; `failed` on clustering error. Poll until `ready`, then GET /source-topics/runs/{runId}/topics.","example":"ready","allOf":[{"$ref":"#/components/schemas/SourceTopicTopicsStatus"}]},"topicsCompletedAt":{"type":"string","description":"When topic clustering finished (null until ready/failed).","format":"date-time","nullable":true,"example":"2026-06-25T13:41:02.000Z"}},"required":["id","status","totalSources","processed","vectorized","skippedNoMeta","skippedPreMeta","failed","params","createdAt","updatedAt","completedAt","topicsStatus","topicsCompletedAt"]},"SourceTopicRunStatus":{"type":"string","enum":["pending","running","completed","failed"],"description":"Lifecycle status of the run."},"SourceTopicRunsListResponse":{"type":"object","properties":{"runs":{"description":"The project's topic-extraction runs, most recent first.","type":"array","items":{"$ref":"#/components/schemas/SourceTopicRunResponse"}}},"required":["runs"]},"SourceTopicTopicResponse":{"type":"object","properties":{"id":{"type":"string","description":"Topic (cluster) UUID.","example":"019dd32e-b19e-7956-88f6-4b9a877f3697"},"rank":{"type":"number","description":"1-based priority rank within the run (1 = highest citation weight at analysis time).","example":1},"label":{"type":"string","description":"LLM-assigned topic label.","example":"Electric vehicle charging"},"keywords":{"description":"Keywords summarizing the topic.","example":["ev charging","charging network","fast charger"],"type":"array","items":{"type":"string"}},"size":{"type":"number","description":"Number of source snapshots grouped in this topic.","example":14},"memberPointIds":{"description":"Qdrant point ids of the sources in this topic.","example":["019dd32e-b19e-7956-88f6-4b9a877f3697"],"type":"array","items":{"type":"string"}}},"required":["id","rank","label","keywords","size","memberPointIds"]},"SourceTopicTopicsListResponse":{"type":"object","properties":{"topics":{"description":"The run topics (clusters), biggest first.","type":"array","items":{"$ref":"#/components/schemas/SourceTopicTopicResponse"}}},"required":["topics"]},"SourceTopicTopicsStatus":{"type":"string","enum":["pending","clustering","ready","failed"],"description":"Topic-clustering lifecycle, independent of embedding `status`. `pending` while embedding; `clustering` once the topic job runs; `ready` when topics are available; `failed` on clustering error. Poll until `ready`, then GET /source-topics/runs/{runId}/topics."},"SourceTopicsExtractDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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}}},"SourceTopicsExtractResponse":{"type":"object","properties":{"runId":{"type":"string","description":"Run UUID. Poll its status via GET /api/v1/source-topics/runs/{runId} (or the list endpoint) to track progress.","example":"019dd32e-b19e-7956-88f6-4b9a877f3697"},"enqueued":{"type":"number","description":"Number of source topic-extraction jobs enqueued (one per distinct (url, month) matching the filters). Jobs are deduped at the queue level, so re-triggering with the same scope is idempotent. Sources whose page metadata was not cached are skipped by the worker and are not represented in this count beyond their enqueue.","example":248}},"required":["runId","enqueued"]},"SourceTopicsPreviewCategorization":{"type":"object","properties":{"totalDomains":{"type":"number","description":"Distinct source domains in the selected set.","example":18},"categorized":{"type":"number","description":"Selected domains that are fully categorised (status `done`).","example":15},"uncategorized":{"type":"number","description":"Selected domains not yet categorised (status is null, `pending` or `failed`).","example":3},"pending":{"type":"boolean","description":"True when any selected domain is still mid-flight in the categorisation pipeline (status `pending` or `failed`) — categorisation may still complete on its own.","example":true},"allCategorized":{"type":"boolean","description":"True when every selected domain is categorised (uncategorized === 0) — safe to run the topic analysis with full category coverage.","example":false}},"required":["totalDomains","categorized","uncategorized","pending","allCategorized"]},"SourceTopicsPreviewCoverage":{"type":"object","properties":{"withMeta":{"type":"number","description":"Snapshots with stored page metadata — guaranteed to be analysed.","example":51},"preMeta":{"type":"number","description":"Snapshots older than metadata collection — these will be skipped.","example":9},"uncertain":{"type":"number","description":"Snapshots whose metadata availability is only known at run time — they may be analysed or skipped.","example":6}},"required":["withMeta","preMeta","uncertain"]},"SourceTopicsPreviewDomain":{"type":"object","properties":{"sourceDomainId":{"type":"string","description":"Source domain UUID.","example":"d1f8c3a2-9b4e-4c7a-8f21-6e0a5b2c9d10"},"domain":{"type":"string","description":"Root domain name.","example":"reddit.com"},"sourceCount":{"type":"number","description":"Number of selected source snapshots (distinct url + month) on this domain that the extraction would process.","example":12},"citationCount":{"type":"number","description":"Total citation count (distinct AI responses) across this domain’s selected sources — the metric the top-N ranking is based on.","example":248},"categorizationStatus":{"description":"Source-categorisation lifecycle state of this domain: `done` = categorised, `pending`/`failed` = still in the categorisation pipeline, null = never queued. Use to spot sources missing a category before extracting.","nullable":true,"example":"done","allOf":[{"$ref":"#/components/schemas/SourceDomainCategorizationStatus"}]},"isCategorized":{"type":"boolean","description":"Convenience flag — true when categorizationStatus is `done`.","example":true}},"required":["sourceDomainId","domain","sourceCount","citationCount","categorizationStatus","isCategorized"]},"SourceTopicsPreviewRelationships":{"type":"object","properties":{"ownedDomains":{"type":"number","description":"Number of source domains mapped as `owned` for this project (relationship overlay). Zero means content-gap cannot mark any topic as covered — every topic would read as a gap until the brand’s domains are mapped.","example":3},"competitorDomains":{"type":"number","description":"Number of source domains mapped as `competitor` for this project. Zero means competitor presence can never be detected.","example":5}},"required":["ownedDomains","competitorDomains"]},"SourceTopicsPreviewResponse":{"type":"object","properties":{"totalSources":{"type":"number","description":"Number of source snapshots (distinct url + month) selected — the exact set the extraction endpoint would enqueue. Capped at `limit`.","example":100},"limit":{"type":"number","description":"Maximum number of sources selected (top-N by citation count).","example":100},"coverage":{"description":"Estimated analysis coverage of the selected snapshots: withMeta is guaranteed in the topic map, preMeta will be skipped, uncertain is resolved at run time. Buckets sum to totalSources.","allOf":[{"$ref":"#/components/schemas/SourceTopicsPreviewCoverage"}]},"domains":{"description":"Selected sources grouped by domain, ordered by sourceCount descending (then citationCount). Lets the user assess what the extraction will hit.","type":"array","items":{"$ref":"#/components/schemas/SourceTopicsPreviewDomain"}},"categorization":{"description":"Source-categorisation coverage of the selected domains — check before extracting whether the sources have been categorised.","allOf":[{"$ref":"#/components/schemas/SourceTopicsPreviewCategorization"}]},"relationships":{"description":"Project-level relationship-overlay readiness. Content-gap presence (owned/competitor) is only meaningful once these are mapped.","allOf":[{"$ref":"#/components/schemas/SourceTopicsPreviewRelationships"}]}},"required":["totalSources","limit","coverage","domains","categorization","relationships"]},"SourceUrlQueriesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"sourceDomainId":{"type":"string","description":"Source domain ID.","example":"0199c3a4-7f2b-7c31-9d55-2b0e4f6a8c11"},"url":{"type":"string","description":"Full URL to get queries for.","example":"https://www.reddit.com/r/technology/comments/abc123/title"}},"required":["sourceDomainId","url"]},"SourceUrlQueriesResponse":{"type":"object","properties":{"queries":{"description":"Queries that produced AI responses citing this URL, ordered by citationCount descending.","type":"array","items":{"$ref":"#/components/schemas/SourceUrlQueryPoint"}}},"required":["queries"]},"SourceUrlQueryPoint":{"type":"object","properties":{"queryId":{"type":"string","description":"Query UUID.","example":"01234567-89ab-cdef-0123-456789abcdef"},"queryText":{"type":"string","description":"Query text (the prompt sent to the AI model).","example":"What are the best project management tools?"},"type":{"description":"The type of question the query asks. Null for queries that have not been classified.","nullable":true,"allOf":[{"$ref":"#/components/schemas/QueryType"}]},"citationCount":{"type":"number","description":"Number of AI responses for this query that cited this URL on this domain.","example":3}},"required":["queryId","queryText","type","citationCount"]},"SourcesBreakdownDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"dimension":{"type":"string","description":"Which axis to aggregate citations by. Required — `type` (source-type leaf), `group` (source-type group), `relationship` (owned/competitor/partner_affiliate/independent), or `controllability` (owned/earnable/hard/unknown, derived from type + relationship).","enum":["type","group","relationship","controllability"],"example":"type"}},"required":["dimension"]},"SourcesBreakdownPoint":{"type":"object","properties":{"key":{"type":"string","description":"Bucket key for the selected `dimension`.","example":"news_media"},"label":{"type":"string","description":"Human-readable label for the bucket.","example":"News & Press"},"citations":{"type":"number","description":"Number of citations in scope that fall in this bucket.","example":128},"percentage":{"type":"number","description":"Share of in-scope citations in this bucket (0–100, one decimal).","example":24.6}},"required":["key","label","citations","percentage"]},"SourcesBreakdownResponse":{"type":"object","properties":{"dimension":{"type":"string","description":"The axis the citations were aggregated by.","enum":["type","group","relationship","controllability"],"example":"type"},"totalCitations":{"type":"number","description":"Total in-scope citations (denominator for `percentage`; includes the `other`/`independent` buckets).","example":520},"rows":{"description":"Per-bucket citation counts, descending by count. Only non-zero buckets are returned.","type":"array","items":{"$ref":"#/components/schemas/SourcesBreakdownPoint"}}},"required":["dimension","totalCitations","rows"]},"StanceDistributionDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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 a single brand (entity) — omit for all brands.","example":"550e8400-e29b-41d4-a716-446655440000"}}},"StancePoint":{"type":"object","properties":{"entityId":{"type":"string","description":"Entity (brand) id."},"displayName":{"type":"string","description":"Brand display name.","example":"Acme"},"isPrimary":{"type":"boolean","description":"Whether this is a primary/owned brand."},"mentions":{"type":"number","description":"Total entity_mentions in scope (classified or not).","example":42},"sentimentScore":{"type":"number","description":"Average brand sentiment score (1-100) across mentions.","example":72},"positive":{"type":"number","description":"Positive-sentiment mentions.","example":24},"neutral":{"type":"number","description":"Neutral-sentiment mentions.","example":14},"negative":{"type":"number","description":"Negative-sentiment mentions.","example":4},"chosen":{"type":"number","description":"The answer put the brand forward as the pick.","example":8},"mentioned":{"type":"number","description":"Arguments given about the brand, without being the pick.","example":12},"named":{"type":"number","description":"Named only, no argument.","example":10},"negativeMentioned":{"type":"number","description":"Arguments given against it.","example":2},"negativeNamed":{"type":"number","description":"Named among the negatives, no argument.","example":1},"withStance":{"type":"number","description":"Sum of the five buckets (rows with a stance).","example":33}},"required":["entityId","displayName","isPrimary","mentions","sentimentScore","positive","neutral","negative","chosen","mentioned","named","negativeMentioned","negativeNamed","withStance"]},"StanceReason":{"type":"object","properties":{"evidenceSpan":{"type":"string","nullable":true,"description":"Verbatim quote from the response."},"sentiment":{"type":"string","nullable":true,"enum":["positive","neutral","negative","mixed"]},"themeLabel":{"type":"string","nullable":true,"description":"The theme this evidence rolls up to."}},"required":["evidenceSpan","sentiment","themeLabel"]},"SuperThemeMemberTheme":{"type":"object","properties":{"themeId":{"type":"string","description":"Canonical theme id."},"label":{"type":"string","description":"Theme label (humanized slug while provisional)."},"status":{"type":"string","description":"Theme status (provisional | stable)."},"mentionCount":{"type":"number","description":"Mention count for this theme in scope.","example":12},"sentimentScore":{"type":"number","description":"Average sentiment (1 very negative … 100 very positive).","example":64.2},"positive":{"type":"number","description":"Positive-sentiment mention count.","example":8},"neutral":{"type":"number","description":"Neutral-sentiment mention count.","example":3},"negative":{"type":"number","description":"Negative-sentiment mention count.","example":1}},"required":["themeId","label","status","mentionCount","sentimentScore","positive","neutral","negative"]},"SuperThemePoint":{"type":"object","properties":{"superThemeId":{"type":"string","description":"Super-theme id (stable across recomputes)."},"label":{"type":"string","description":"Super-theme label, derived from its dominant member theme.","example":"Product quality"},"themeCount":{"type":"number","description":"Number of member themes.","example":5},"mentionCount":{"type":"number","description":"Total mentions across the super-theme member themes (in scope).","example":47},"sentimentScore":{"type":"number","description":"Mention-weighted average sentiment across member themes.","example":58.9},"themes":{"description":"Member themes, ordered by mention count desc.","type":"array","items":{"$ref":"#/components/schemas/SuperThemeMemberTheme"}}},"required":["superThemeId","label","themeCount","mentionCount","sentimentScore","themes"]},"SupportedCountry":{"type":"object","properties":{"value":{"type":"string","description":"ISO 3166-1 alpha-2 code","example":"US"},"label":{"type":"string","description":"Display name","example":"United States of America"}},"required":["value","label"]},"SupportedLanguage":{"type":"object","properties":{"value":{"type":"string","description":"BCP-47-style language code","example":"en"},"label":{"type":"string","description":"Display name","example":"English"}},"required":["value","label"]},"SupportedLocalesResponse":{"type":"object","properties":{"countries":{"description":"Allowlist of supported country codes (ISO 3166-1 alpha-2) with display labels.","example":[{"value":"US","label":"United States of America"},{"value":"BE","label":"Belgium"}],"type":"array","items":{"$ref":"#/components/schemas/SupportedCountry"}},"languages":{"description":"Allowlist of supported language codes (BCP-47-style) with display labels.","example":[{"value":"en","label":"English"},{"value":"fr","label":"French"}],"type":"array","items":{"$ref":"#/components/schemas/SupportedLanguage"}}},"required":["countries","languages"]},"TableEnvelope":{"type":"object","properties":{"metric":{"type":"string","description":"Metric id (matches discovery list)"},"title":{"type":"string","description":"Human-readable card title"},"description":{"type":"string","description":"Short description rendered under the title"},"columns":{"type":"array","items":{"$ref":"#/components/schemas/MetricColumnSpec"}},"rows":{"type":"array","description":"Row data; keys match `columns[].key`","items":{"type":"object","additionalProperties":{}}},"defaultSort":{"$ref":"#/components/schemas/MetricDefaultSort"},"highlight":{"description":"Row-level highlight rule (e.g. tint the leader row)","allOf":[{"$ref":"#/components/schemas/MetricHighlightRule"}]}},"required":["metric","title","columns","rows"]},"TagEntitiesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"tagType":{"type":"string","description":"Which tag system the tagIds belong to","enum":["query","execution"],"example":"query"},"tagIds":{"description":"Tag IDs to get entities for","example":["42","43"],"type":"array","items":{"type":"string"}},"limit":{"type":"number","description":"Entities returned per tag: the top N in the sort order. The full list is not available (a large project holds about a million tag-entity rows); use `focusKeys` to get an entity outside the top N, and `entityCount` for the size of the full list.","default":20,"maximum":100,"example":15},"focusKeys":{"description":"Display keys (the `displayKey` of an entity row) to return in `focus` with their rank, even outside the top `limit`. The project's primary entity is always in `focus`.","example":["550e8400-e29b-41d4-a716-446655440000"],"type":"array","items":{"type":"string"}},"sort":{"description":"Per-tag sort. Defaults to visibility DESC.","example":[{"field":"visibility","direction":"desc"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}},"required":["tagType","tagIds"]},"TagEntitiesResponse":{"type":"object","properties":{"tags":{"description":"Per-tag entity results.","type":"array","items":{"$ref":"#/components/schemas/TagEntitiesTopResult"}}},"required":["tags"]},"TagEntitiesTopResult":{"type":"object","properties":{"tagId":{"type":"string","description":"Tag ID (UUID).","example":"550e8400-e29b-41d4-a716-446655440000"},"resultCount":{"type":"number","description":"Total number of AI responses for this tag in the filtered scope (denominator for visibility).","example":340},"entities":{"description":"Detected entities for this tag with their metrics, in the request sort order (default visibility descending).","type":"array","items":{"$ref":"#/components/schemas/TagEntityPoint"}},"entityCount":{"type":"number","description":"Number of entities in the full list for this tag (`entities` holds the top `limit` only). An entity absent from the tag ranks after all of them (entityCount + 1).","example":1240},"focus":{"description":"The `focusKeys` entities and the project's primary entity with their rank, even outside the top `limit`. Ordered by rank. An entity with no mention in this tag is absent.","type":"array","items":{"$ref":"#/components/schemas/TagEntityFocusPoint"}}},"required":["tagId","resultCount","entities","entityCount","focus"]},"TagEntityFocusPoint":{"type":"object","properties":{"displayKey":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable entity name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project (i.e. the project's own brand or product).","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":false},"isCompetitor":{"type":"boolean","description":"Whether this entity is a configured competitor of the project.","example":true},"mentionCount":{"type":"number","description":"Raw mention count of this entity in the tag's responses.","example":265},"visibility":{"type":"number","description":"Visibility: % of this tag's responses that mention this entity.","example":77.9},"shareOfVoice":{"type":"number","description":"Share of voice (%): this entity's responses over the sum of every entity's responses for this tag. Same definition as /analytics/visibility/share-of-voice.","example":32.1},"avgRanking":{"type":"number","description":"Average position rank across all mention entries for this entity (not deduped). Lower values mean the entity tends to appear higher/earlier in responses.","example":1.8},"sentimentScore":{"type":"number","description":"Average sentiment score for this entity's mentions within this tag. Scale: 0 (most negative) to 100 (most positive). Computed across raw mention rows (not deduped).","example":74.2},"sentiment":{"description":"Sentiment breakdown — counts of entity mention entries by sentiment category (positive, neutral, negative).","allOf":[{"$ref":"#/components/schemas/TagEntitySentiment"}]},"rank":{"type":"number","description":"Position of this entity in the tag's full list, in the request sort order (1 = first).","example":7}},"required":["displayKey","displayName","isOwned","isPrimary","isCompetitor","mentionCount","visibility","shareOfVoice","avgRanking","sentimentScore","sentiment","rank"]},"TagEntityPoint":{"type":"object","properties":{"displayKey":{"type":"string","description":"Canonical entity ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable entity name.","example":"Acme Corp"},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project (i.e. the project's own brand or product).","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":false},"isCompetitor":{"type":"boolean","description":"Whether this entity is a configured competitor of the project.","example":true},"mentionCount":{"type":"number","description":"Raw mention count of this entity in the tag's responses.","example":265},"visibility":{"type":"number","description":"Visibility: % of this tag's responses that mention this entity.","example":77.9},"shareOfVoice":{"type":"number","description":"Share of voice (%): this entity's responses over the sum of every entity's responses for this tag. Same definition as /analytics/visibility/share-of-voice.","example":32.1},"avgRanking":{"type":"number","description":"Average position rank across all mention entries for this entity (not deduped). Lower values mean the entity tends to appear higher/earlier in responses.","example":1.8},"sentimentScore":{"type":"number","description":"Average sentiment score for this entity's mentions within this tag. Scale: 0 (most negative) to 100 (most positive). Computed across raw mention rows (not deduped).","example":74.2},"sentiment":{"description":"Sentiment breakdown — counts of entity mention entries by sentiment category (positive, neutral, negative).","allOf":[{"$ref":"#/components/schemas/TagEntitySentiment"}]}},"required":["displayKey","displayName","isOwned","isPrimary","isCompetitor","mentionCount","visibility","shareOfVoice","avgRanking","sentimentScore","sentiment"]},"TagEntitySentiment":{"type":"object","properties":{"positive":{"type":"number","description":"Number of entity mention entries classified as positive sentiment.","example":165},"neutral":{"type":"number","description":"Number of entity mention entries classified as neutral sentiment.","example":72},"negative":{"type":"number","description":"Number of entity mention entries classified as negative sentiment.","example":28}},"required":["positive","neutral","negative"]},"TagGroupResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"tagType":{"type":"string","enum":["query","execution"],"description":"Which tag taxonomy this folder organizes: \"query\" or \"execution\". Immutable."},"name":{"type":"string"},"color":{"type":"string","description":"Color of the tag group in hex format.","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","tagType","name","createdAt","updatedAt"]},"TagGroupTagType":{"type":"string","enum":["query","execution"]},"TagJobExecutionNewResponse":{"type":"object","properties":{"id":{"type":"string","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","description":"Unique identifier for the tag"},"project":{"type":"object","description":"The project this tag belongs to","example":"a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"},"name":{"type":"string","example":"important","description":"Name of the tag"},"color":{"type":"string","example":"#3B82F6","description":"Color of the tag in hex format"},"matchingMode":{"type":"string","example":"exact","description":"How the tag is matched to responses: `exact` links only responses whose text contains the tag name, `semantic` links responses by meaning, using the name, description and exclusion.","enum":["exact","semantic"]},"description":{"type":"string","description":"Semantic tags: what the tag covers.","nullable":true},"exclusion":{"type":"string","description":"Semantic tags: what the tag does not cover.","nullable":true},"groupId":{"type":"string","description":"ID of the tag group node this tag is filed under; null when ungrouped.","format":"uuid","nullable":true}},"required":["id","project","name","color","matchingMode"]},"TagJobExecutionSelectionDto":{"type":"object","properties":{"mode":{"type":"string","enum":["include","all"],"description":"How the target set is defined. \"include\" acts on the given ids; \"all\" acts on everything matching the filter except the excluded ids."},"ids":{"description":"Ids to act on. Required when mode is \"include\".","example":["018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"],"type":"array","items":{"type":"string"}},"excludedIds":{"description":"Ids to subtract from the matched set. Only used when mode is \"all\".","example":["018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"],"type":"array","items":{"type":"string"}},"filter":{"description":"Filters identifying the matched response tags. Used when mode is \"all\".","allOf":[{"$ref":"#/components/schemas/ListTagJobExecutionNewDto"}]}},"required":["mode"]},"TagResponse":{"type":"object","properties":{"id":{"type":"number","example":1,"description":"Unique identifier for the tag"},"project":{"type":"object","description":"The project this tag belongs to","example":"a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"},"name":{"type":"string","example":"feature","description":"Name of the tag"},"color":{"type":"string","example":"#3B82F6","description":"Color of the tag in hex format"},"queryCount":{"type":"number","example":5,"description":"Number of queries associated with this tag"},"groupId":{"type":"string","description":"ID of the tag group node this tag is filed under; null when ungrouped.","format":"uuid","nullable":true},"groupName":{"type":"string","description":"Name of the tag group node this tag is filed under; null when ungrouped.","nullable":true}},"required":["id","project","name","color"]},"TagSelectionDto":{"type":"object","properties":{"mode":{"type":"string","enum":["include","all"],"description":"How the target set is defined. \"include\" acts on the given ids; \"all\" acts on everything matching the filter except the excluded ids."},"ids":{"description":"Ids to act on. Required when mode is \"include\".","example":["018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"],"type":"array","items":{"type":"string"}},"excludedIds":{"description":"Ids to subtract from the matched set. Only used when mode is \"all\".","example":["018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"],"type":"array","items":{"type":"string"}},"filter":{"description":"Filters identifying the matched tags. Used when mode is \"all\".","allOf":[{"$ref":"#/components/schemas/ListTagDto"}]}},"required":["mode"]},"TagSourcePoint":{"type":"object","properties":{"domain":{"type":"string","description":"Root domain name (e.g. reddit.com).","example":"reddit.com"},"resultCount":{"type":"number","description":"Number of distinct AI responses (for this tag) that cited at least one page from this domain. A single response citing 3 reddit.com pages counts as 1.","example":102},"citationRate":{"type":"number","description":"Citation rate — how often this domain appears across the tag's AI responses. Formula: (resultCount / tag resultCount) × 100.","example":30},"pageCount":{"type":"number","description":"Total number of individual page/URL citations from this domain (not deduped). One AI response may cite multiple pages from the same domain, each counted separately.","example":178},"shareOfCitations":{"type":"number","description":"Share of citations — this domain's portion of all page citations for the tag. Formula: (pageCount / totalPageCitations) × 100.","example":19.9},"brandPageCount":{"type":"number","description":"Number of cited pages from this domain where the selected entities (brand) were also mentioned. Subset of pageCount — only pages that also reference the brand.","example":45},"trueReach":{"type":"number","description":"True reach — the percentage of this domain's cited pages that also mention the brand. Formula: (brandPageCount / pageCount) × 100.","example":25.3}},"required":["domain","resultCount","citationRate","pageCount","shareOfCitations","brandPageCount","trueReach"]},"TagSourcesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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 the tagId belongs to","enum":["query","execution"],"example":"query"},"tagId":{"type":"string","description":"Tag ID to get sources for. Exactly one of tagId / groupId must be set.","example":"42"},"groupId":{"type":"string","description":"Tag group ID to get sources for — aggregates the member tags of the group. Exactly one of tagId / groupId must be set.","format":"uuid","example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"},"entityIds":{"description":"Entity IDs for brand reach calculation (defaults to primary non-blacklisted)","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}},"limit":{"type":"number","description":"Max number of source domains to return (top N by result count)","example":15},"sort":{"description":"Sorting options for the returned source domains. Allowed fields: domain, resultCount, citationRate, pageCount, shareOfCitations, brandPageCount, trueReach.","example":[{"field":"resultCount","direction":"desc"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}},"required":["tagType"]},"TagSourcesResponse":{"type":"object","properties":{"tagId":{"type":"string","description":"Tag ID (UUID).","example":"550e8400-e29b-41d4-a716-446655440000"},"resultCount":{"type":"number","description":"Total number of AI responses for this tag in the filtered scope. Used as the denominator for citationRate.","example":340},"totalPageCitations":{"type":"number","description":"Sum of pageCount across all source domains for this tag. Used as the denominator for shareOfCitations.","example":892},"sources":{"description":"Per-domain citation and reach statistics for this tag, ordered by resultCount descending.","type":"array","items":{"$ref":"#/components/schemas/TagSourcePoint"}}},"required":["tagId","resultCount","totalPageCitations","sources"]},"TagsMatrixDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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"},"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"}},"bucketSize":{"type":"string","description":"Time bucket granularity","enum":["day","week","month"],"example":"week"},"entityIds":{"description":"Entity IDs to compute visibility for (defaults to primary non-blacklisted)","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}}},"required":["tagType","bucketSize"]},"TagsMatrixPoint":{"type":"object","properties":{"bucket":{"type":"string","description":"Start of the time bucket (ISO 8601). Granularity depends on the requested bucketSize (day/week/month).","example":"2025-01-01T00:00:00.000Z"},"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":"#FF5733"},"totalResponses":{"type":"number","description":"Total number of AI responses tagged with this tag in this time bucket (denominator for visibilityPct).","example":50},"presentIn":{"type":"number","description":"Number of AI responses in this bucket (for this tag) where the selected entities are mentioned (numerator for visibilityPct). Counted once per AI response.","example":20},"visibilityPct":{"type":"number","description":"Visibility percentage — how often the selected entities appear in responses tagged with this tag in this bucket. Formula: (presentIn / totalResponses) × 100.","example":40}},"required":["bucket","tagId","tagName","tagColor","totalResponses","presentIn","visibilityPct"]},"TagsModelsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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 break down by model (query tags or response/execution tags)","enum":["query","execution"],"example":"execution"},"entityIds":{"description":"Entity IDs for the project brand (defaults to primary non-blacklisted)","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}},"tagIds":{"description":"Restrict to specific tag IDs (omit for all tags)","example":["pricing","features"],"type":"array","items":{"type":"string"}},"limit":{"type":"number","description":"Max number of tags (rows) to return for this page, ranked by visibility. Defaults to 5.","example":5,"default":5},"offset":{"type":"number","description":"Number of tags (rows) to skip for pagination. Defaults to 0.","example":0,"default":0}},"required":["tagType"]},"TagsModelsModelPoint":{"type":"object","properties":{"model":{"type":"string","description":"Raw model identifier (e.g. \"gpt-5-mini\").","example":"gpt-5-mini"},"resultCount":{"type":"number","description":"Total number of AI responses for this (tag, model) cell — denominator for cell visibility.","example":120},"visibility":{"type":"number","description":"Project brand visibility for this (tag, model) cell — percentage of responses that mention the brand. Formula: (brand-mentioning responses / resultCount) × 100.","example":42.5}},"required":["model","resultCount","visibility"]},"TagsModelsResponse":{"type":"object","properties":{"total":{"type":"number","description":"Total number of tags with data in the filtered scope (across all pages). Use with limit/offset for pagination.","example":27},"tags":{"description":"Page of tags ranked by project brand visibility descending, each with a per-model breakdown.","type":"array","items":{"$ref":"#/components/schemas/TagsModelsTagPoint"}}},"required":["total","tags"]},"TagsModelsTagPoint":{"type":"object","properties":{"tagId":{"type":"string","description":"Tag ID.","example":"550e8400-e29b-41d4-a716-446655440000"},"tagName":{"type":"string","description":"Tag display name.","example":"Week 1"},"tagColor":{"type":"string","description":"Tag color as a hex string.","example":"#4f46e5"},"resultCount":{"type":"number","description":"Total number of AI responses for this tag across all models (denominator for tag-level visibility).","example":340},"visibility":{"type":"number","description":"Project brand visibility across the whole tag, as the percentage of responses that mention the brand. Computed from raw counts so it does not drift from rounded per-cell values.","example":40},"models":{"description":"Per-model breakdown of brand visibility within this tag, ordered by visibility descending.","type":"array","items":{"$ref":"#/components/schemas/TagsModelsModelPoint"}}},"required":["tagId","tagName","tagColor","resultCount","visibility","models"]},"TagsPresenceDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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}}},"TagsPresencePoint":{"type":"object","properties":{"tagId":{"type":"string","description":"Execution-tag ID (UUID).","example":"550e8400-e29b-41d4-a716-446655440000"},"tagName":{"type":"string","description":"Tag display name.","example":"Week 22"},"tagColor":{"type":"string","description":"Tag color as a hex string.","example":"#FF5733"},"presencePct":{"type":"number","description":"Percentage of AI responses (matching the filters) that carry this tag. Range 0-100, rounded to two decimals.","example":72.5}},"required":["tagId","tagName","tagColor","presencePct"]},"TagsStatsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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"]},"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":"Total mentions of the project brand in this tag's responses.","example":80},"visibility":{"type":"number","description":"Project brand visibility: % of this tag's responses that mention the brand.","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 brand's responses over the sum of every entity's responses for this tag. Same definition as /analytics/visibility/share-of-voice.","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"]},"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"]},"TagsSummaryDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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"},"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"}},"entityIds":{"description":"Entity IDs to compute visibility for (defaults to primary non-blacklisted)","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}}},"required":["tagType"]},"TagsSummaryPoint":{"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":"#FF5733"},"totalResponses":{"type":"number","description":"Total number of AI responses tagged with this tag (denominator for visibilityPct). Scoped by the request filters (project, date range, models, platforms).","example":200},"presentIn":{"type":"number","description":"Number of AI responses (for this tag) where the selected entities are mentioned (numerator for visibilityPct). Counted once per AI response.","example":80},"visibilityPct":{"type":"number","description":"Visibility percentage — how often the selected entities appear in responses tagged with this tag. Formula: (presentIn / totalResponses) × 100.","example":40},"avgPositionRank":{"type":"number","description":"Average position rank for the selected entities within responses tagged with this tag. Lower values mean the entity tends to appear higher/earlier in responses.","example":2.5}},"required":["tagId","tagName","tagColor","totalResponses","presentIn","visibilityPct","avgPositionRank"]},"TagsTrendsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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"},"bucketSize":{"type":"string","description":"Time bucket granularity","enum":["day","week","month"],"example":"week"},"entityIds":{"description":"Entity IDs for the project brand (defaults to primary non-blacklisted)","example":["a3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"],"type":"array","items":{"type":"string"}},"tagIds":{"description":"Restrict to specific tag IDs (omit for all tags)","example":["pricing","support","features"],"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"}}},"required":["tagType","bucketSize"]},"TagsTrendsPoint":{"type":"object","properties":{"bucket":{"type":"string","description":"Start of the time bucket (ISO 8601). Granularity depends on the requested bucketSize (day/week/month).","example":"2026-03-03T00:00:00.000Z"},"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 in this time bucket (denominator for projectVisibility).","example":48},"projectMentionCount":{"type":"number","description":"Number of AI responses (for this tag, in this bucket) where the project brand entities were detected.","example":37},"projectVisibility":{"type":"number","description":"Project brand visibility — how often the project brand appears in this tag's responses for this bucket. Formula: (projectMentionCount / resultCount) × 100.","example":77.1}},"required":["bucket","tagId","tagName","tagColor","resultCount","projectMentionCount","projectVisibility"]},"ThemeAnalysisLastRun":{"type":"object","properties":{"startedAt":{"type":"string","description":"When the last cluster pass started.","example":"2026-07-14T10:12:04.000Z"},"finishedAt":{"type":"string","description":"When the last cluster pass ended; null if it is still running. This is when the themes you are looking at were last recomputed.","nullable":true,"example":"2026-07-14T10:18:41.000Z"}},"required":["startedAt"]},"ThemeAnalysisStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"Coarse pipeline state. running = mentions are being extracted/clustered right now; pending = completed prompt runs are queued for the next poll (~1 min); failed = the last cluster pass failed or was killed (OOM/SIGKILL) and the project is not converging — see lastRun; idle = nothing outstanding, the project is up to date.","enum":["idle","pending","running","failed"],"example":"running"},"enabled":{"type":"boolean","description":"Whether theme analysis is enabled for this project.","example":true},"pendingJobs":{"type":"number","description":"Completed prompt runs not yet handed off to analysis (the poller will pick them up within ~1 min).","example":3},"analyzedJobs":{"type":"number","description":"Completed prompt runs already handed off to analysis.","example":28},"unclusteredMentions":{"type":"number","description":"Theme mentions extracted but not yet assigned a theme (clustering in flight).","example":14},"themeMentions":{"type":"number","description":"Total theme mentions extracted for this project so far.","example":412},"themes":{"type":"number","description":"Distinct themes the project mentions have resolved into.","example":23},"lastActivityAt":{"type":"string","description":"ISO timestamp of the most recent extracted mention, or null if none yet.","example":"2026-06-25T10:12:04.000Z","nullable":true},"lastRun":{"description":"The last stage-3 cluster pass, or null if the project has never been clustered.","nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/ThemeAnalysisLastRun"}]}},"required":["status","enabled","pendingJobs","analyzedJobs","unclusteredMentions","themeMentions","themes","lastActivityAt"]},"ThemeClusteringConfigDto":{"type":"object","properties":{"mint":{"type":"number","description":"Resolve: below this cosine, mint a new theme.","example":0.74,"minimum":0,"maximum":1},"fold":{"type":"number","description":"Resolve: at/above this cosine, fold into the nearest theme.","example":0.82,"minimum":0,"maximum":1},"consGrayLo":{"type":"number","description":"Consolidate: below this cosine, not a merge candidate.","example":0.74,"minimum":0,"maximum":1},"autoMerge":{"type":"number","description":"Consolidate: at/above this cosine, auto-merge without the LLM.","example":0.92,"minimum":0,"maximum":1},"singletonAbsorbLo":{"type":"number","description":"Consolidate: raw floor for the singleton-absorption pass.","example":0.62,"minimum":0,"maximum":1},"whitenGate":{"type":"number","description":"Consolidate: whitened-cosine anisotropy guard on merge candidates (higher = splits more aggressively; 0 disables).","example":0.2,"minimum":-1,"maximum":1},"superAssignFloor":{"type":"number","description":"Super-themes: min whitened cosine to assign a theme to a category; below it the theme stays ungrouped.","example":0.05,"minimum":-1,"maximum":1},"superMax":{"type":"number","description":"Super-themes: max super-themes per project.","example":15,"minimum":1,"maximum":100}}},"ThemeEntityCell":{"type":"object","properties":{"themeId":{"type":"string","description":"Canonical theme id."},"label":{"type":"string","description":"Theme label.","example":"Reliability"},"entityId":{"type":"string","description":"Brand (entity) id."},"mentionCount":{"type":"number","description":"Mentions of this theme for this brand.","example":7},"sentimentScore":{"type":"number","description":"Average sentiment (1-100).","example":68},"positive":{"type":"number","description":"Positive mentions.","example":5},"neutral":{"type":"number","description":"Neutral mentions.","example":1},"negative":{"type":"number","description":"Negative mentions.","example":1}},"required":["themeId","label","entityId","mentionCount","sentimentScore","positive","neutral","negative"]},"ThemeMentionItem":{"type":"object","properties":{"id":{"type":"string","description":"Theme mention id."},"aiResponseId":{"type":"string","description":"The AI response this mention was extracted from."},"initiatedAt":{"type":"string","description":"When the response was generated (ISO 8601)."},"model":{"type":"string","nullable":true,"description":"AI model that produced the response."},"entityId":{"type":"string","nullable":true,"description":"Canonical entity (brand) id, null for subject-anchored perception."},"entityName":{"type":"string","nullable":true,"description":"Canonical entity (brand) name."},"isPrimary":{"type":"boolean","description":"Whether the entity is the project primary brand."},"phrase":{"type":"string","description":"Raw extracted surface phrase."},"evidenceSpan":{"type":"string","nullable":true,"description":"Verbatim quote from the AI response (the evidence)."},"sentiment":{"type":"string","nullable":true,"enum":["positive","neutral","negative","mixed"]},"sentimentScore":{"type":"number","nullable":true,"description":"Sentiment score 1–100."},"strength":{"type":"string","nullable":true,"enum":["peripheral","supporting","central"]},"responseOrder":{"type":"number","nullable":true,"description":"0-based order of appearance in the response."},"queryId":{"type":"string","nullable":true,"description":"The query that was answered."},"queryText":{"type":"string","nullable":true,"description":"The query prompt text."}},"required":["id","aiResponseId","initiatedAt","model","entityId","entityName","isPrimary","phrase","evidenceSpan","sentiment","sentimentScore","strength","responseOrder","queryId","queryText"]},"ThemeMentionsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"themeId":{"type":"string","description":"Canonical theme id to drill into.","example":"550e8400-e29b-41d4-a716-446655440000"},"sentiment":{"type":"string","description":"Restrict to a single sentiment.","enum":["positive","neutral","negative","mixed"]},"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}},"required":["themeId"]},"ThemeMentionsResponse":{"type":"object","properties":{"mentions":{"type":"array","items":{"$ref":"#/components/schemas/ThemeMentionItem"}},"page":{"$ref":"#/components/schemas/Paging"}},"required":["mentions","page"]},"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"]},"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"]},"ThemesByThemeDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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}}},"ThemesByThemeListDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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"]},"TimeseriesEnvelope":{"type":"object","properties":{"metric":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"xAxis":{"$ref":"#/components/schemas/MetricAxisSpec"},"yAxis":{"$ref":"#/components/schemas/MetricAxisSpec"},"series":{"type":"array","items":{"$ref":"#/components/schemas/MetricSeriesSpec"}},"points":{"type":"array","description":"Time-bucketed data; keys match xAxis.key + each series.key","items":{"type":"object","additionalProperties":{}}}},"required":["metric","title","xAxis","yAxis","series","points"]},"UnlinkManyTagsDto":{"type":"object","properties":{"tagIds":{"description":"IDs of the tags to unlink","example":[1,2,3],"type":"array","items":{"type":"number"}},"queryIds":{"description":"IDs of the queries to unlink the tags from","example":["0199c3a4-7f2b-7c31-9d55-2b0e4f6a8c11","0199c3a4-8d10-7e42-b6a7-91c3f5027d64"],"type":"array","items":{"type":"string"}}},"required":["tagIds","queryIds"]},"UnlinkManyTagsJobExecutionNewDto":{"type":"object","properties":{"tagIds":{"description":"UUIDs of the tags to unlink","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"type":"array","items":{"type":"string"}},"jobExecutionIds":{"description":"UUIDs of the job executions to unlink the tags from","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],"type":"array","items":{"type":"string"}}},"required":["tagIds","jobExecutionIds"]},"UpdateEntityDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the entity","example":"Acme Corporation"},"type":{"type":"string","description":"Type/category of the entity","enum":["brand","person","company","other"],"example":"brand"},"level":{"type":"string","nullable":true,"description":"Tier inside the project's entity type, one of its levelVocab (GET /entity-types); null clears it","example":"city"},"isOwned":{"type":"boolean","description":"Whether this entity belongs to (is owned by) the current project","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the project's primary entity","example":false},"isCompetitor":{"type":"boolean","description":"Whether this entity is tracked as a competitor","example":false},"isBlacklisted":{"type":"boolean","description":"Whether this entity is blacklisted and should be excluded from tracking","example":false},"groupId":{"type":"string","description":"UUID of the entity group to assign this entity to. Pass null to remove the entity from its current group.","nullable":true,"example":"3f9a8b2c-1d4e-4f6a-9b8c-7d6e5f4a3b2c"},"domains":{"description":"Complete set of domains associated with this entity (replace/sync). Each URL is normalised to a registrable root domain. Omit to leave domains untouched; pass an empty array to clear all. Used to drive the project-scoped \"competitor\" source category.","example":["hubspot.com","hubspot.fr"],"type":"array","items":{"type":"string"}}}},"UpdateEntityGroupDto":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable display name of the entity group.","example":"Competitor Brands"},"parentId":{"type":"string","description":"Parent group of a division. Send a group ID to attach or move the division, or null to detach it into a standalone division. Groups cannot have a parent.","format":"uuid","nullable":true,"example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"}}},"UpdateProjectDto":{"type":"object","properties":{"name":{"type":"string","description":"The name of the project","example":"My Project"},"description":{"type":"string","description":"The description of the project","example":"My Project Description"},"website":{"type":"string","description":"The website of the project","example":"https://www.mentionlab.io"},"industry":{"type":"string","description":"The industry of the project","example":"Cosmetics"},"entityType":{"type":"string","enum":["brands","brands_and_products","countries_cities","organisations","people","places","facilities","events"],"description":"What the project tracks; defaults to brands. A type other than brands must be available to the organisation (GET /entity-types). A change applies to new answers only.","example":"countries_cities"},"analysisInstructions":{"type":"string","nullable":true,"maxLength":500,"description":"Extra instructions added to the analysis of the project's answers; they apply to new answers only. An empty string clears them.","example":"Do not count retailers or marketplaces as brands."},"currentPo":{"type":"string","description":"Active purchase order. When set, future buys / refunds / commitment releases that target this project snapshot the value onto the resulting lot for accountant statements.","example":"PO-2026-Q2-1234"},"themeAnalysisEnabled":{"type":"boolean","description":"Enable the async Brand Perception & Intelligence theme-analysis batch. When on, completed jobs are picked up (within ~1 min) and analyzed.","example":true},"themeLanguage":{"type":"string","description":"Language for extracted themes. A language code ('en', 'fr', 'nl', …) forces a monolingual taxonomy; 'auto' lets themes follow each answer's own language.","enum":["auto","en","fr","nl","de","es","it","pt"],"example":"en"},"themeClusteringConfig":{"description":"Per-project theme clustering threshold overrides. Any omitted knob falls back to the global default. Takes effect on the next cluster pass; rebuild to re-apply to existing themes.","allOf":[{"$ref":"#/components/schemas/ThemeClusteringConfigDto"}]}}},"UpdateQueryDto":{"type":"object","properties":{"tagIds":{"description":"List of tag IDs to associate with this query","example":[1,2,3],"type":"array","items":{"type":"number"}},"type":{"description":"The type of question the query asks. Pass null to clear the type.","nullable":true,"allOf":[{"$ref":"#/components/schemas/QueryType"}]}}},"UpdateTagDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tag. Must not start or end with a quote or apostrophe.","example":"feature"},"color":{"type":"string","description":"Color of the tag in hex format","example":"#3B82F6"},"groupId":{"type":"string","description":"ID of the query-taxonomy tag group to file the tag under, or null for ungrouped. Group assignment never triggers tag re-matching.","format":"uuid","nullable":true,"example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"}}},"UpdateTagGroupDto":{"type":"object","properties":{"name":{"type":"string","description":"New name of the tag group, unique per project and taxonomy. Must not start or end with a quote or apostrophe.","example":"Personas"},"color":{"type":"string","description":"New color of the tag group in hex format.","example":"#10B981"}}},"UpdateTagJobExecutionNewDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tag. Must not start or end with a quote or apostrophe.","example":"important"},"color":{"type":"string","description":"Color of the tag in hex format","example":"#3B82F6"},"matchingMode":{"type":"string","description":"How the tag is matched to responses: `exact` links only responses whose text contains the tag name (default), `semantic` links responses by meaning, using the name, description and exclusion.","enum":["exact","semantic"],"example":"exact"},"description":{"type":"string","description":"Semantic tags: what the tag covers. Changing it marks the tag for a history re-sync.","nullable":true,"maxLength":300,"example":"Checked baggage rules, weight limits and extra bag fees."},"exclusion":{"type":"string","description":"Semantic tags: what the tag does not cover. Changing it marks the tag for a history re-sync.","nullable":true,"maxLength":200,"example":"Cabin bags."},"confirmVectorization":{"type":"boolean","description":"Ignored. Semantic tags no longer index the project responses, so there is nothing to confirm.","deprecated":true,"example":true},"groupId":{"type":"string","description":"ID of the execution-taxonomy tag group to file the tag under, or null for ungrouped. Group assignment never triggers tag re-matching or re-embedding.","format":"uuid","nullable":true,"example":"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"}}},"VisibilityEntitiesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"entityIds":{"description":"Limit the returned rows to these entity IDs. This narrows which entities appear without changing the total responses used to compute visibility.","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}}}},"VisibilityEntityPoint":{"type":"object","properties":{"displayKey":{"type":"string","description":"Unique identifier for the entity or entity group. In per-entity mode this is the canonical entity ID; in grouped mode it is the entity group ID (or entity ID if ungrouped).","example":"550e8400-e29b-41d4-a716-446655440000"},"displayName":{"type":"string","description":"Human-readable name of the entity or entity group.","example":"Acme Corp"},"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered date range (denominator for visibilityPct). Scoped by the request filters (project, date range, models, platforms, tags).","example":150},"presentIn":{"type":"number","description":"Number of AI responses that mention this entity/group (numerator for visibilityPct). A response mentioning multiple variants of the same canonical entity is counted once.","example":42},"visibilityPct":{"type":"number","description":"Visibility percentage — how often this entity/group appears across AI responses. Formula: (presentIn / totalResponses) × 100.","example":28,"nullable":true},"avgPositionRank":{"type":"number","description":"Weighted average position rank for this entity across all AI responses that mention it. Lower values mean the entity tends to appear higher/earlier in responses. Weighted by mention count to account for canonical entity merging.","example":2.5},"isOwned":{"type":"boolean","description":"Whether this entity is owned by the project (i.e. the project's own brand or product).","example":true},"isPrimary":{"type":"boolean","description":"Whether this entity is the primary (main) entity for the project.","example":true},"isCompetitor":{"type":"boolean","description":"Whether this entity is a configured competitor of the project.","example":false},"mentionCount":{"type":"number","description":"Total number of mention entries for this entity (raw count before dedup). Used to compute avgMentionsPerResult.","example":56},"sentimentScore":{"type":"number","description":"Average sentiment score for this entity across all mentions. Scale: 0 (most negative) to 100 (most positive). Null when the entity has no scored mentions.","example":72.3,"nullable":true},"sentiment":{"description":"Sentiment breakdown counts for this entity.","allOf":[{"$ref":"#/components/schemas/VisibilityEntitySentiment"}]},"avgMentionsPerResult":{"type":"number","description":"Average number of times this entity is mentioned per AI response that mentions it. Formula: mentionCount / presentIn. Values > 1 indicate repeated prominence.","example":1.33,"nullable":true}},"required":["displayKey","displayName","totalResponses","presentIn","visibilityPct","avgPositionRank","isOwned","isPrimary","isCompetitor","mentionCount","sentimentScore","sentiment","avgMentionsPerResult"]},"VisibilityEntitySentiment":{"type":"object","properties":{"positive":{"type":"number","description":"Count of mentions with positive sentiment.","example":35},"neutral":{"type":"number","description":"Count of mentions with neutral sentiment.","example":15},"negative":{"type":"number","description":"Count of mentions with negative sentiment.","example":6}},"required":["positive","neutral","negative"]},"VisibilityTimeseriesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"entityTypes":{"type":"array","description":"Filter which entity types to include in results. Accepted values: \"owned\", \"primary\", \"competitor\". Defaults to all types when omitted.","example":["owned","primary","competitor"],"items":{"type":"string","enum":["owned","primary","competitor"]}},"bucketSize":{"type":"string","description":"Time bucket granularity","enum":["day","week","month"],"example":"day"},"entityIds":{"description":"Restrict results to these entity IDs.","example":["3fa85f64-5717-4562-b3fc-2c963f66afa6"],"type":"array","items":{"type":"string"}}},"required":["bucketSize"]},"YoutubeChannelListItem":{"type":"object","properties":{"channelId":{"type":"string","description":"YouTube-side channel ID (e.g. \"UCsXVk37bltHxD1rDPwtNM8Q\").","example":"UCsXVk37bltHxD1rDPwtNM8Q"},"name":{"type":"string","description":"Channel display name (from latest snapshot).","example":"Kurzgesagt – In a Nutshell"},"country":{"type":"string","description":"ISO country code for the channel (from latest snapshot).","nullable":true,"example":"DE"},"thumbnailUrl":{"type":"string","description":"Channel thumbnail URL (medium size, from latest snapshot).","nullable":true,"example":"https://yt3.ggpht.com/abc123/mqdefault.jpg"},"subscriberCount":{"type":"string","description":"Subscriber count at time of latest snapshot.","nullable":true,"example":"23400000"},"videoCount":{"type":"number","description":"Video count at time of latest snapshot.","nullable":true,"example":215},"citedVideoCount":{"type":"number","description":"Distinct YouTube videos from this channel cited in scope.","example":4},"citationCount":{"type":"number","description":"Distinct AI responses in scope that cited any video from this channel.","example":57},"citationShare":{"type":"number","description":"This channel's share of YouTube-video citations in scope. Formula: (citationCount / total AI responses citing any YT video in scope) × 100. Null when no YouTube citations exist in scope (denominator = 0).","nullable":true,"example":7.78},"citationRate":{"type":"number","description":"Citation rate — how often this channel appears across ALL AI responses in scope. Formula: (citationCount / totalResponses) × 100. Null when no AI responses exist in scope (denominator = 0).","nullable":true,"example":3.42},"uniqueQueryCount":{"type":"number","description":"Distinct queries in scope whose AI responses cited any video from this channel.","example":11},"firstCitedAt":{"type":"string","description":"Earliest citation timestamp within filter scope.","example":"2026-04-01T09:12:34.000Z"},"lastCitedAt":{"type":"string","description":"Latest citation timestamp within filter scope.","example":"2026-04-24T18:45:12.000Z"},"lastSnapshotId":{"type":"string","description":"Internal UUID of the latest `social_youtube_channels` snapshot used as the source of metadata fields on this row. Useful for debugging.","example":"01924f6a-7b90-7c11-9b8a-123456789abc"}},"required":["channelId","name","country","thumbnailUrl","subscriberCount","videoCount","citedVideoCount","citationCount","citationShare","citationRate","uniqueQueryCount","firstCitedAt","lastCitedAt","lastSnapshotId"]},"YoutubeChannelsDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"page":{"type":"number","description":"Page number (1-based) of the result set to return.","default":1,"example":1},"pageSize":{"type":"number","description":"Number of items to return per page (maximum 200).","default":50,"example":50},"search":{"type":"string","description":"Case-insensitive substring filter on the latest channel name, used to narrow results to a specific channel (e.g. the audited brand). SQL wildcards ('%', '_') and backslashes are escaped and treated literally.","example":"MrBeast","maxLength":200},"channelCountry":{"type":"string","description":"Drill-down filter that restricts results to channels whose home country (from the latest snapshot) matches this ISO code, powering the per-country sheet. Distinct from the `country` scope filter, which represents the query/market country.","example":"US"},"sort":{"description":"Ordering rules applied to the result set. Each entry pairs a sortable field (name, country, subscriberCount, videoCount, citedVideoCount, citationCount, citationShare, citationRate, uniqueQueryCount, firstCitedAt, lastCitedAt) with a sort direction.","example":[{"field":"citationCount","direction":"desc"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"YoutubeChannelsResponse":{"type":"object","properties":{"globalYoutubeCitations":{"type":"number","description":"Total distinct AI responses in scope that cited any YouTube video. Denominator for `citationShare`.","example":733},"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope. Used as the denominator for `citationRate`.","example":2140},"results":{"description":"Per-channel rows for the current page.","type":"array","items":{"$ref":"#/components/schemas/YoutubeChannelListItem"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["globalYoutubeCitations","totalResponses","results","page"]},"YoutubeChannelsTimeseriesChannel":{"type":"object","properties":{"channelId":{"type":"string","description":"YouTube-side channel ID.","example":"UCsXVk37bltHxD1rDPwtNM8Q"},"channelName":{"type":"string","description":"Channel display name from the latest snapshot.","example":"Kurzgesagt – In a Nutshell"}},"required":["channelId","channelName"]},"YoutubeChannelsTimeseriesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"bucketSize":{"type":"string","description":"Time bucket granularity","enum":["day","week","month"],"example":"day"}},"required":["bucketSize"]},"YoutubeChannelsTimeseriesPoint":{"type":"object","properties":{"bucket":{"type":"string","description":"Start of the time bucket (ISO 8601). Granularity depends on the requested bucketSize (day/week/month).","example":"2026-03-01T00:00:00.000Z"},"channelId":{"type":"string","description":"YouTube-side channel ID.","example":"UCsXVk37bltHxD1rDPwtNM8Q"},"channelName":{"type":"string","description":"Channel display name from the latest snapshot.","example":"Kurzgesagt – In a Nutshell"},"resultCount":{"type":"number","description":"Number of distinct AI responses that cited any video from this channel within this bucket.","example":12},"citationShare":{"type":"number","description":"This channel's per-bucket share among AI responses citing any YouTube channel in the bucket. Formula: (resultCount / bucket total YT-citing responses) × 100. Per-bucket shares across the 5 top channels can sum to ≤ 100% (other channels outside the top 5 also have citations).","example":22.5}},"required":["bucket","channelId","channelName","resultCount","citationShare"]},"YoutubeChannelsTimeseriesResponse":{"type":"object","properties":{"channels":{"description":"The top 5 channels ordered by total citations across the full date range. Every bucket in `points` will contain an entry for each of these 5 channels (0 if absent).","type":"array","items":{"$ref":"#/components/schemas/YoutubeChannelsTimeseriesChannel"}},"points":{"description":"Flat array of data points — one entry per (bucket × channel) combination. Ordered by bucket ascending, then by channel rank descending within each bucket.","type":"array","items":{"$ref":"#/components/schemas/YoutubeChannelsTimeseriesPoint"}}},"required":["channels","points"]},"YoutubeCountriesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"page":{"type":"number","description":"Page number (1-based).","default":1,"example":1},"pageSize":{"type":"number","description":"Items per page (max 200).","default":50,"example":50},"sort":{"description":"Sort options applied to the result. Sortable fields: country, citedChannelCount, citedVideoCount, citationCount, citationShare, citationRate, uniqueQueryCount.","example":[{"field":"citationCount","direction":"desc"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"YoutubeCountriesResponse":{"type":"object","properties":{"globalYoutubeCitations":{"type":"number","description":"Total distinct AI responses in scope that cited any YouTube video. Denominator for `citationShare`.","example":733},"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope. Used as the denominator for `citationRate`.","example":2140},"results":{"description":"Per-country rows for the current page.","type":"array","items":{"$ref":"#/components/schemas/YoutubeCountryListItem"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["globalYoutubeCitations","totalResponses","results","page"]},"YoutubeCountryListItem":{"type":"object","properties":{"country":{"type":"string","description":"ISO country code of the cited channel, from its latest snapshot. NULL groups channels that have no country assigned. This is the channel ORIGIN country — distinct from the request-level `country` filter, which scopes by the query/market country.","nullable":true,"example":"US"},"citedChannelCount":{"type":"number","description":"Distinct YouTube channels from this country whose videos were cited in scope.","example":12},"citedVideoCount":{"type":"number","description":"Distinct YouTube videos from this country's channels cited in scope.","example":38},"citationCount":{"type":"number","description":"Distinct AI responses in scope that cited any video from a channel in this country.","example":156},"citationShare":{"type":"number","description":"This country's share of YouTube-video citations in scope. Formula: (citationCount / total AI responses citing any YT video in scope) × 100. Shares across countries can sum to >100% because one AI response may cite videos from channels in multiple countries. Null when no YouTube citations exist in scope (denominator = 0).","nullable":true,"example":21.28},"citationRate":{"type":"number","description":"Citation rate — how often this country's channels appear across ALL AI responses in scope. Formula: (citationCount / totalResponses) × 100. Null when no AI responses exist in scope (denominator = 0).","nullable":true,"example":7.3},"uniqueQueryCount":{"type":"number","description":"Distinct queries in scope whose AI responses cited any video from a channel in this country.","example":34}},"required":["country","citedChannelCount","citedVideoCount","citationCount","citationShare","citationRate","uniqueQueryCount"]},"YoutubeKpisDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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}}},"YoutubeKpisResponse":{"type":"object","properties":{"videoCount":{"type":"number","description":"Number of unique YouTube videos (by `video_id`) linked to at least one citation in scope.","example":42},"citationCount":{"type":"number","description":"Number of distinct AI responses in scope that cited at least one YouTube video. Same value as `globalYoutubeCitations` on the list endpoints.","example":733},"citationsPerVideo":{"type":"number","description":"Ratio `citationCount / videoCount`, rounded to 2 decimals. Null when `videoCount = 0` (division by zero).","nullable":true,"example":17.45},"channelCount":{"type":"number","description":"Number of unique YouTube channels (by `channel_id`) whose videos were cited in scope.","example":15},"countryCount":{"type":"number","description":"Number of distinct non-null countries across the latest snapshot of each cited channel. Channels with a NULL country are excluded from this count.","example":7}},"required":["videoCount","citationCount","citationsPerVideo","channelCount","countryCount"]},"YoutubeVideoListItem":{"type":"object","properties":{"videoId":{"type":"string","description":"YouTube-side video ID (11 chars).","example":"_wbc-UEur4c"},"url":{"type":"string","description":"Canonical YouTube watch URL, synthesized from `videoId`.","example":"https://www.youtube.com/watch?v=_wbc-UEur4c"},"title":{"type":"string","description":"Video title (from latest snapshot).","nullable":true,"example":"The Egg - A Short Story"},"thumbnailUrl":{"type":"string","description":"Video thumbnail URL (medium size, from latest snapshot).","nullable":true,"example":"https://i.ytimg.com/vi/_wbc-UEur4c/mqdefault.jpg"},"publishedAt":{"type":"string","description":"When the video was published on YouTube.","nullable":true,"example":"2019-10-04T14:00:00.000Z"},"durationSeconds":{"type":"number","description":"Length of the video in seconds, parsed from YouTube's ISO 8601 duration on the latest snapshot. Null when YouTube did not return a duration (e.g. livestream in progress) or the value was unparseable.","nullable":true,"example":933},"isShort":{"type":"boolean","description":"Whether the citing URL is a YouTube Shorts URL (`/shorts/<id>`). Derived from the citation URL at the producer; the YouTube Data API itself does not expose a \"short\" flag. Reflects the latest snapshot.","example":false},"viewCount":{"type":"string","description":"View count at time of latest snapshot.","nullable":true,"example":"42385123"},"likeCount":{"type":"string","description":"Like count at time of latest snapshot.","nullable":true,"example":"1254321"},"commentCount":{"type":"string","description":"Comment count at time of latest snapshot.","nullable":true,"example":"48291"},"favoriteCount":{"type":"string","description":"Favorite count at time of latest snapshot.","nullable":true,"example":"0"},"channelId":{"type":"string","description":"YouTube-side channel ID that owns this video.","example":"UCsXVk37bltHxD1rDPwtNM8Q"},"channelName":{"type":"string","description":"Channel display name (from latest channel snapshot).","nullable":true,"example":"Kurzgesagt – In a Nutshell"},"citationCount":{"type":"number","description":"Distinct AI responses in scope that cited this video (any snapshot).","example":42},"citationShare":{"type":"number","description":"This video's share of YouTube-video citations in scope. Formula: (citationCount / total AI responses citing any YT video in scope) × 100. Null when no YouTube citations exist in scope (denominator = 0).","nullable":true,"example":5.73},"citationRate":{"type":"number","description":"Citation rate — how often this video appears across ALL AI responses in scope. Formula: (citationCount / totalResponses) × 100. Null when no AI responses exist in scope (denominator = 0).","nullable":true,"example":1.96},"uniqueQueryCount":{"type":"number","description":"Distinct queries in scope whose AI responses cited this video.","example":7},"firstCitedAt":{"type":"string","description":"Earliest citation timestamp (initiated_at of the oldest AI response that cited this video, within filter scope).","example":"2026-04-01T09:12:34.000Z"},"lastCitedAt":{"type":"string","description":"Latest citation timestamp within filter scope.","example":"2026-04-24T18:45:12.000Z"},"lastSnapshotId":{"type":"string","description":"Identifier of the most recent metadata snapshot for this video.","example":"01924f6a-7b90-7c11-9b8a-123456789abc"}},"required":["videoId","url","title","thumbnailUrl","publishedAt","durationSeconds","isShort","viewCount","likeCount","commentCount","favoriteCount","channelId","channelName","citationCount","citationShare","citationRate","uniqueQueryCount","firstCitedAt","lastCitedAt","lastSnapshotId"]},"YoutubeVideoQueriesDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"videoId":{"type":"string","description":"YouTube-side video ID (11 chars, e.g. \"_wbc-UEur4c\"). Matches all snapshots of the same video, not a specific snapshot UUID.","example":"_wbc-UEur4c"}},"required":["videoId"]},"YoutubeVideoQueriesResponse":{"type":"object","properties":{"queries":{"description":"Queries that produced AI responses citing this YouTube video, ordered by citationCount descending.","type":"array","items":{"$ref":"#/components/schemas/YoutubeVideoQueryPoint"}}},"required":["queries"]},"YoutubeVideoQueryPoint":{"type":"object","properties":{"queryId":{"type":"string","description":"Query UUID.","example":"01234567-89ab-cdef-0123-456789abcdef"},"queryText":{"type":"string","description":"Query text (the prompt sent to the AI model).","example":"What are the best educational YouTube channels?"},"type":{"description":"The type of question the query asks. Null for queries that have not been classified.","nullable":true,"allOf":[{"$ref":"#/components/schemas/QueryType"}]},"citationCount":{"type":"number","description":"Number of distinct AI responses for this query that cited this YouTube video (any snapshot).","example":3}},"required":["queryId","queryText","type","citationCount"]},"YoutubeVideosDto":{"type":"object","properties":{"startDate":{"type":"string","description":"Start date (inclusive)","example":"2025-01-01"},"endDate":{"type":"string","description":"End date (inclusive)","example":"2025-01-31"},"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"]},"hasAds":{"type":"string","description":"Filter by sponsored-ad presence: \"ads\" (only with ads), \"no_ads\" (only without), \"all\" (no filter). Legacy true/false values are still accepted.","enum":["all","ads","no_ads"]},"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: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"execTagMode":{"type":"string","description":"Execution tag matching mode: \"and\" matches ALL tags (default, the dashboard's), \"or\" matches ANY tag.","enum":["and","or"]},"timezone":{"type":"string","deprecated":true,"description":"Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.","example":"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},"page":{"type":"number","description":"Page number (1-based).","default":1,"example":1},"pageSize":{"type":"number","description":"Items per page (max 200).","default":50,"example":50},"channelId":{"type":"string","description":"Drill-down filter: restrict results to videos from a specific YouTube channel. Uses the YouTube-side channel ID, not our internal UUID.","example":"UCsXVk37bltHxD1rDPwtNM8Q"},"channelCountry":{"type":"string","description":"Drill-down filter: restrict results to videos whose channel's home country (latest snapshot) matches this ISO code. Powers the per-country sheet. Distinct from the `country` scope filter, which is the query/market country.","example":"US"},"search":{"type":"string","description":"Case-insensitive substring filter on the latest video title. SQL wildcards ('%', '_') and backslashes are escaped and treated literally.","example":"product review"},"sort":{"description":"Ordering directives applied to the result set. Each entry pairs a sortable field with a direction. Allowed fields: title, publishedAt, durationSeconds, isShort, viewCount, likeCount, commentCount, channelName, citationCount, citationShare, citationRate, uniqueQueryCount, firstCitedAt, lastCitedAt.","example":[{"field":"viewCount","direction":"DESC"}],"type":"array","items":{"$ref":"#/components/schemas/SortOptions"}}}},"YoutubeVideosResponse":{"type":"object","properties":{"globalYoutubeCitations":{"type":"number","description":"Total distinct AI responses in scope that cited any YouTube video. Denominator for `citationShare`.","example":733},"totalResponses":{"type":"number","description":"Total number of AI responses in the filtered scope. Used as the denominator for `citationRate`.","example":2140},"results":{"description":"Per-video rows for the current page.","type":"array","items":{"$ref":"#/components/schemas/YoutubeVideoListItem"}},"page":{"description":"Pagination metadata.","allOf":[{"$ref":"#/components/schemas/Paging"}]}},"required":["globalYoutubeCitations","totalResponses","results","page"]}}}}