> ## Documentation Index > Fetch the complete documentation index at: https://docs.mentionlab.io/llms.txt > Use this file to discover all available pages before exploring further. # Get per-advertiser ad share > 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. ## OpenAPI ````yaml https://api.mentionlab.io/api/docs-json post /api/analytics/ads/advertisers openapi: 3.0.0 info: title: MentionLab Public API v0.5.8-rc description: '' version: 0.5.8-rc contact: {} servers: - url: https://api.mentionlab.io security: [] tags: [] paths: /api/analytics/ads/advertisers: post: tags: - Analytics - Ads summary: Get per-advertiser ad share 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' components: schemas: 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 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 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 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 ````