openapi: 3.2.0 info: title: V1 Analytics API version: v1 servers: - url: https://api.airops.com variables: defaultHost: default: api.airops.com tags: - name: Analytics x-parent: Brand Kits paths: /public_api/brand_kits/{brand_kit_id}/analytics: post: summary: Get Analytic description: Query analytics data for a Brand Kit with flexible metrics, dimensions, and filters. tags: - Analytics operationId: getBrandKitsAnalytic security: - bearer: [] responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array description: Query results with requested dimensions and metrics items: type: object meta: type: object properties: row_count: type: integer description: Number of rows returned in this response total_count: type: integer description: Total number of rows available across all pages (ignores limit/offset) execution_time_ms: type: integer description: Query execution time in milliseconds start_date: type: string description: Actual start date used for the query (YYYY-MM-DD), including defaults end_date: type: string description: Actual end date used for the query (YYYY-MM-DD), including defaults data_availability: type: object description: Information about data availability for the brand kit properties: earliest_data_date: type: - string - 'null' description: Date of the first completed analysis (ISO 8601). Null if none exist. latest_data_date: type: - string - 'null' description: Date of the most recent completed analysis (ISO 8601). Null if none exist. requested_period_has_data: type: boolean description: Whether any completed analyses exist within the requested date range error: type: string description: Error message if query failed query: type: object description: Summary of the query parameters used properties: metrics: type: array items: type: string dimensions: type: array items: type: string filters: type: object grain: type: string limit: type: integer offset: type: integer chart_image_url: type: - string - 'null' description: QuickChart.io URL for visualizing the data. Useful for displaying charts or embedding in Notion/Google docs, etc. DO NOT DISPLAY THIS IMAGE DIRECTLY TO THE USER. Null when no data is available to visualize. '400': description: Bad request - invalid parameters, filters, or sort options '401': description: Unauthorized - invalid or missing authentication token '404': description: Not found - resource does not exist '412': description: Precondition failed - AEO not configured for this brand kit parameters: - name: brand_kit_id in: path required: true schema: type: integer description: The Brand Kit ID requestBody: required: true content: application/json: schema: properties: brand_kit_id: type: integer description: The Brand Kit ID to query analytics for metrics: type: array items: type: string enum: - mention_rate - positive_answer_rate - share_of_voice - citation_rate - citation_share - citation_count - sentiment_score - average_position - answer_count - first_mention_rate description: 'Metrics to calculate. Options: mention_rate (brand mention frequency, 0-100), positive_answer_rate (percentage of answers where your brand is positively mentioned, out of all answers where you have been mentioned and sentiment is determined; null when unavailable), share_of_voice (percentage of total mentions, 0-100), citation_rate (citation frequency, 0-100), citation_share (relative citation volume, 0-100), citation_count (total citations), sentiment_score (0-100, negative to positive; null when unavailable), average_position (ranking placement), answer_count (total responses), first_mention_rate (first position frequency, 0-100)' dimensions: type: array items: type: string enum: - date - provider - topic - country - persona - domain - competitor - domain_category - theme description: Dimensions to group by (max 3). grain: type: string enum: - daily - weekly - monthly - total description: 'Time granularity for aggregation. Default: total' start_date: type: string description: 'Start date (YYYY-MM-DD). Default: 7 days ago' end_date: type: string description: End date (YYYY-MM-DD). Defaults to yesterday. Must be before today because today's data may still be processing and is incomplete — yesterday is used to ensure robust, complete data. Leave blank unless a specific date is requested. providers: type: array items: type: string enum: - chat_gpt - gemini - perplexity - google_ai_mode - google_ai_overview - claude - grok - microsoft_copilot description: Filter by AI providers topics: type: array items: type: integer description: Filter by topic IDs tags: description: Filter by tags. A bare array of tag IDs matches ANY (IN). An object {"operator":"IN"|"HAS_ALL"|"NOT_IN","value":[ids]} selects the operator; HAS_ALL matches only items tagged with every listed tag; NOT_IN matches only items tagged with none of the listed tags. anyOf: - type: array items: type: integer - type: object properties: operator: type: string enum: - IN - HAS_ALL - NOT_IN value: type: array items: type: integer required: - operator - value countries: type: array items: type: string enum: - AE - AR - AT - AU - BE - BR - CA - CH - CL - CN - CO - CZ - DE - DK - ES - FI - FR - GB - GR - HR - HU - ID - IE - IL - IN - IS - IT - JP - KR - MX - MY - NL - 'NO' - NZ - PE - PH - PL - PT - SE - SG - TH - TR - US - VN description: Filter by country codes (ISO 3166-1 alpha-2) personas: type: array items: type: integer description: Filter by persona IDs themes: type: array items: type: integer description: Filter sentiment data by theme IDs. Only applies to sentiment_score metric. brand_mentioned: type: string enum: - brand - category description: 'Filter by prompt type. Options: category (generic prompts - recommended for accurate visibility metrics), brand (prompts mentioning the brand). Defaults to category if not specified' limit: type: integer description: 'Maximum rows to return (1-5000). Default: 100' offset: type: integer description: 'Number of records to skip for pagination. Default: 0. Use with limit to page through large result sets.' order_by: type: string description: Custom sort order (e.g., "citation_count DESC") required: - brand_kit_id - metrics type: object components: securitySchemes: bearer: type: http scheme: bearer